Improve order example

[jonathanstanley]

The javascript api allows ordering the rows on a referenced table:

supabase/apps/docs/spec/supabase_js_v2.yml

Line 6108 in 1e9bbb2

.order('name', { referencedTable: 'cities', ascending: false })

however the example is a little confusing because both the selected table and referenced table have a column called name

supabase/apps/docs/spec/supabase_js_v2.yml

Lines 6100 to 6108 in 1e9bbb2

	const { data, error } = await supabase
	.from('countries')
	.select(`
	name,
	cities (
	name
	)
	`)
	.order('name', { referencedTable: 'cities', ascending: false })

it took me a bit to discover the note buried at the bottom:

supabase/apps/docs/spec/supabase_js_v2.yml

Lines 6157 to 6159 in 1e9bbb2

	description: |
	Ordering on referenced tables doesn't affect the ordering of
	the parent table.

From there, I don't think it is clear for the reader what referencedTable does.

• Is it ascending or descending (or does it have to match the main table)?
• Is there a way to sort the main table according to the row's referenced value?
• What if the referenced table has a key override: towns:cities(name)?

I think it would be very good if the cities(name) was replaced with something like cities(id) so the reader knows the order("name") is referring to