From 84608622f79c35dbb1b9d8ebb2137276f1ea2800 Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Tue, 2 Aug 2022 22:03:10 +0200 Subject: [PATCH] Adds the full usage spec --- apps/reference/_supabase_js/usage.mdx | 2248 ++++++++++++++++++- spec/supabase_js_v1_sdk.yaml | 2854 +++++++++++++------------ 2 files changed, 3708 insertions(+), 1394 deletions(-) diff --git a/apps/reference/_supabase_js/usage.mdx b/apps/reference/_supabase_js/usage.mdx index a0f439e601a..5b5422ba87c 100644 --- a/apps/reference/_supabase_js/usage.mdx +++ b/apps/reference/_supabase_js/usage.mdx @@ -999,8 +999,8 @@ const { data: user, error } = await supabase.functions.invoke('hello', { ```js const { data: user, error } = await supabase.functions.invoke('hello', { - headers: { - "my-custom-header": 'my-custom-header-value' + headers: { + "my-custom-header": 'my-custom-header-value' }, body: JSON.stringify({ foo: 'bar' }) }) @@ -1171,7 +1171,7 @@ ac.abort() ### Notes - By default, every time you run `insert()`, the client library will make a `select` to return the full record. -This is convenient, but it can also cause problems if your Policies are not configured to allow the `select` operation. +This is convenient, but it can also cause problems if your Policies are not configured to allow the `select` operation. If you are using Row Level Security and you are encountering problems, try setting the `returning` param to `minimal`. @@ -1258,7 +1258,7 @@ const { data, error } = await supabase const { data, error } = await supabase .from('users') .update(` - address: { + address: { street: 'Melrose Place', postcode: 90210 } @@ -1279,7 +1279,7 @@ const { data, error } = await supabase ### Notes -- Primary keys should be included in the data payload in order for an update to work correctly. +- Primary keys should be included in the data payload in order for an update to work correctly. - Primary keys must be natural, not surrogate. There are however, [workarounds](https://github.com/PostgREST/postgrest/issues/1118) for surrogate primary keys. @@ -1328,11 +1328,11 @@ const { data, error } = await supabase ```js const { data, error, count } = await supabase .from('users') - .upsert({ - id: 3, message: 'foo', - username: 'supabot' - }, { - count: 'exact' + .upsert({ + id: 3, message: 'foo', + username: 'supabot' + }, { + count: 'exact' }) ``` @@ -1652,7 +1652,7 @@ const subscriptions = supabase.getSubscriptions() ### Notes - Policy permissions required: - - `buckets` permissions: `select` + - `buckets` permissions: `select` - `objects` permissions: none @@ -1671,3 +1671,2229 @@ const { data, error } = await supabase + + +## Get a single bucket + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: `select` + - `objects` permissions: none + + +### Examples + + + +#### Get bucket + +```js +const { data, error } = await supabase + .storage + .getBucket('avatars') +``` + + + + + + +## Create a new bucket + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: `insert` + - `objects` permissions: none + + +### Examples + + + +#### Create bucket + +```js +const { data, error } = await supabase + .storage + .createBucket('avatars', { public: false }) +``` + + + + + + +## Empty a bucket + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: `select` + - `objects` permissions: `select` and `delete` + + +### Examples + + + +#### Empty bucket + +```js +const { data, error } = await supabase + .storage + .emptyBucket('avatars') +``` + + + + + + +## updateBucket() + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: `update` + - `objects` permissions: none + + +### Examples + + + +#### Update bucket + +```js +const { data, error } = await supabase + .storage + .updateBucket('avatars', { public: false }) +``` + + + + + + +## deleteBucket() + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: `select` and `delete` + - `objects` permissions: none + + +### Examples + + + +#### Delete bucket + +```js +const { data, error } = await supabase + .storage + .deleteBucket('avatars') +``` + + + + + + +## Upload a file + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `insert` +- For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Upload file using `ArrayBuffer` from base64 file data instead, see example below. + + +### Examples + + + +#### Upload file + +```js +const avatarFile = event.target.files[0] +const { data, error } = await supabase + .storage + .from('avatars') + .upload('public/avatar1.png', avatarFile, { + cacheControl: '3600', + upsert: false + }) +``` + + + + +#### Upload file using `ArrayBuffer` from base64 file data + +```js +import { decode } from 'base64-arraybuffer' + +const { data, error } = await supabase + .storage + .from('avatars') + .upload('public/avatar1.png', decode('base64FileData'), { + contentType: 'image/png' + }) +``` + + + + + + +## Update a file + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `update` and `select` +- For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Update file using `ArrayBuffer` from base64 file data instead, see example below. + + +### Examples + + + +#### Update file + +```js +const avatarFile = event.target.files[0] +const { data, error } = await supabase + .storage + .from('avatars') + .update('public/avatar1.png', avatarFile, { + cacheControl: '3600', + upsert: false + }) +``` + + + + +#### Update file using `ArrayBuffer` from base64 file data + +```js +import {decode} from 'base64-arraybuffer' + +const { data, error } = await supabase + .storage + .from('avatars') + .update('public/avatar1.png', decode('base64FileData'), { + contentType: 'image/png' + }) +``` + + + + + + +## Move a file + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `update` and `select` + + +### Examples + + + +#### Move file + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .move('public/avatar1.png', 'private/avatar2.png') +``` + + + + + + +## Copy a file + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `update` and `select` + + +### Examples + + + +#### Copy file + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .copy('public/avatar1.png', 'private/avatar2.png') +``` + + + + + + +## Create a signed URL + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + + +### Examples + + + +#### Create Signed URL + +```js +const { signedURL, error } = await supabase + .storage + .from('avatars') + .createSignedUrl('folder/avatar1.png', 60) +``` + + + + + + +## Sign multiple URLs + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + + +### Examples + + + +#### Create Signed URLs + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60) +``` + + + + + + +## Get public URL + + + + + +### Notes + +- The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [app.supabase.com](https://app.supabase.com), clicking the overflow menu on a bucket and choosing "Make public" +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: none + + +### Examples + + + +#### Returns the URL for an asset in a public bucket + +```js +const { publicURL, error } = supabase + .storage + .from('public-bucket') + .getPublicUrl('folder/avatar1.png') +``` + + + + + + +## Download a file + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + + +### Examples + + + +#### Download file + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .download('folder/avatar1.png') +``` + + + + + + +## from.remove() + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `delete` and `select` + + +### Examples + + + +#### Delete file + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .remove(['folder/avatar1.png']) +``` + + + + + + +## List files + + + + + +### Notes + +- Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + + +### Examples + + + +#### List files in a bucket + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .list('folder', { + limit: 100, + offset: 0, + sortBy: { column: 'name', order: 'asc' }, + }) +``` + + + + +#### Search files in a bucket + +```js +const { data, error } = await supabase + .storage + .from('avatars') + .list('folder', { + limit: 100, + offset: 0, + sortBy: { column: 'name', order: 'asc' }, + search: 'jon' + }) +``` + + + + + + +## Limit rows returned + + + + + +### Notes + +Modifiers can be used on `select()` queries. + +If a Postgres function returns a table response, you can also apply modifiers to the `rpc()` function. + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .limit(1) +``` + + + + +#### With embedded resources + +```js +const { data, error } = await supabase + .from('countries') + .select('name, cities(name)') + .eq('name', 'United States') + .limit(1, { foreignTable: 'cities' }) +``` + + + + + + +## Order results + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name', 'country_id') + .order('id', { ascending: false }) +``` + + + + +#### With embedded resources + +```js +const { data, error } = await supabase + .from('countries') + .select('name, cities(name)') + .eq('name', 'United States') + .order('name', {foreignTable: 'cities'}) +``` + + + + + + +## Select a range of data + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .range(0,3) +``` + + + + + + +## Get a single row of data + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .limit(1) + .single() +``` + + + + + + +## Return a single row if it exists + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .eq('name', 'Singapore') + .maybeSingle() +``` + + + + + + +## Apply multiple filters with OR conditional + + + + + +### Notes + +- `.or()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values. + + ```js + .or('id.in.(6,7), arraycol.cs.{"a","b"}') // Use Postgres list () for in filter. Array {} for array column and 'cs' for contains. + .or(`id.in.(${arrList}),arraycol.cs.{${arr}}`) // You can insert a javascipt array for list or array on array column. + .or(`id.in.(${arrList}),rangecol.cs.[${arrRange})`) // You can insert a javascipt array for list or range on a range column. + ``` + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .or('id.eq.20,id.eq.30') +``` + + + + +#### Use `or` with `and` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .or('id.gt.20,and(name.eq.New Zealand,name.eq.France)') +``` + + + + +#### Use `or` on foreign tables + +```js +const { data, error } = await supabase + .from('countries') + .select('id, cities(*)') + .or('name.eq.Wellington,name.eq.Paris', { foreignTable: "cities" }) +``` + + + + + + +## Apply a "not" filter + + + + + +### Notes + +- `.not()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values. + + ```js + .not('name','eq','Paris') + .not('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains. + .not('rangecol','cs','(1,2]') // Use Postgres range syntax for range column. + .not('id','in','(6,7)') // Use Postgres list () for in filter. + .not('id','in',`(${arr})`) // You can insert a javascript array. + ``` + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .not('name', 'eq', 'Paris') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .not('name', 'eq', 'Paris') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .not('name', 'eq', 'Paris') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .not('name', 'eq', 'Paris') +``` + + + + + + +## Match on several criteria + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .match({name: 'Beijing', country_id: 156}) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .match({name: 'Beijing', country_id: 156}) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .match({name: 'Beijing', country_id: 156}) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .match({name: 'Beijing', country_id: 156}) +``` + + + + + + +## Filter by exact equality + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .eq('name', 'The shire') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .eq('name', 'San Francisco') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .eq('name', 'Mordor') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .eq('name', 'San Francisco') +``` + + + + + + +## Filter by not equal + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .neq('name', 'The shire') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .neq('name', 'San Francisco') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .neq('name', 'Mordor') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .neq('name', 'Lagos') +``` + + + + + + +## Filter by greater than + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .gt('country_id', 250) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .gt('country_id', 250) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .gt('country_id', 250) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .gt('country_id', 250) +``` + + + + + + +## Filter by greater than or equal + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .gte('country_id', 250) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .gte('country_id', 250) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .gte('country_id', 250) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .gte('country_id', 250) +``` + + + + + + +## Filter by less than + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .lt('country_id', 250) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .lt('country_id', 250) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .lt('country_id', 250) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .lt('country_id', 250) +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .lte('country_id', 250) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .lte('country_id', 250) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .lte('country_id', 250) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .lte('country_id', 250) +``` + + + + + + +## Filter by string equality + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .like('name', '%la%') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .like('name', '%la%') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .like('name', '%la%') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .like('name', '%la%') +``` + + + + + + +## Filter by string equality (case insensitive) + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .ilike('name', '%la%') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .ilike('name', '%la%') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .ilike('name', '%la%') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .ilike('name', '%la%') +``` + + + + + + +## Filter by null values + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .is('name', null) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .is('name', null) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .is('name', null) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .is('name', null) +``` + + + + + + +## Filter if in array + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .in('name', ['Rio de Janeiro', 'San Francisco']) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .in('name', ['Rio de Janeiro', 'San Francisco']) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .in('name', ['Rio de Janeiro', 'San Francisco']) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .in('name', ['Rio de Janeiro', 'San Francisco']) +``` + + + + + + +## Filter if TBD + + + + + +### Notes + +- `.contains()` can work on array columns or range columns. + It is very useful for finding rows where a tag array contains all the values in the filter array. + + ```js + .contains('arraycol',["a","b"]) // You can use a javascript array for an array column + .contains('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. + .contains('rangecol','(1,2]') // Use Postgres range syntax for range column. + .contains('rangecol',`(${arr}]`) // You can insert an array into a string. + ``` + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, main_exports') + .contains('main_exports', ['oil']) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .contains('main_exports', ['oil']) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .contains('main_exports', ['oil']) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .contains('main_exports', ['oil']) +``` + + + + + + +## Filter by TBD + + + + + +### Notes + +- `.containedBy()` can work on array columns or range columns. + + ```js + .containedBy('arraycol',["a","b"]) // You can use a javascript array for an array column + .containedBy('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. + .containedBy('rangecol','(1,2]') // Use Postgres range syntax for range column. + .containedBy('rangecol',`(${arr}]`) // You can insert an array into a string. + ``` + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, main_exports') + .containedBy('main_exports', ['cars', 'food', 'machine']) +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .containedBy('main_exports', ['orks', 'surveillance', 'evil']) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .containedBy('main_exports', ['cars', 'food', 'machine']) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .containedBy('main_exports', ['cars', 'food', 'machine']) +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeLt('population_range_millions', '[150, 250]') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeLt('population_range_millions', '[150, 250]') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .rangeLt('population_range_millions', '[150, 250]') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeLt('population_range_millions', '[150, 250]') +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeGt('population_range_millions', '[150, 250]') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeGt('population_range_millions', '[150, 250]') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .rangeGt('population_range_millions', '[150, 250]') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeGt('population_range_millions', '[150, 250]') +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeGte('population_range_millions', '[150, 250]') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeGte('population_range_millions', '[150, 250]') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .rangeGte('population_range_millions', '[150, 250]') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeGte('population_range_millions', '[150, 250]') +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeLte('population_range_millions', '[150, 250]') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeLte('population_range_millions', '[150, 250]') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .rangeLte('population_range_millions', '[150, 250]') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeLte('population_range_millions', '[150, 250]') +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeAdjacent('population_range_millions', '[70, 185]') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeAdjacent('population_range_millions', '[70, 185]') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .rangeAdjacent('population_range_millions', '[70, 185]') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeAdjacent('population_range_millions', '[70, 185]') +``` + + + + + + +## Filter by TBD + + + + + +### Notes + +- `.overlaps()` can work on array columns or range columns. + + ```js + .overlaps('arraycol',["a","b"]) // You can use a javascript array for an array column + .overlaps('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. + .overlaps('rangecol','(1,2]') // Use Postgres range syntax for range column. + .overlaps('rangecol',`(${arr}]`) // You can insert an array into a string. + ``` + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('countries') + .select('name, id, main_exports') + .overlaps('main_exports', ['computers', 'minerals']) +``` + + + + +#### With `update()` + +```js +let countries = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .overlaps('main_exports', ['computers', 'minerals']) +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('countries') + .delete() + .overlaps('main_exports', ['computers', 'minerals']) +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_countries') + .overlaps('main_exports', ['computers', 'minerals']) +``` + + + + + + +## Filter by TBD + + + + + +### Notes + + + +### Examples + + + +#### Text search + +```js +const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat' & 'cat'`, { + config: 'english' + }) +``` + + + + +#### Basic normalization + +```js +const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat' & 'cat'`, { + type: 'plain', + config: 'english' + }) +``` + + + + +#### Full normalization + +```js +const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat' & 'cat'`, { + type: 'phrase', + config: 'english' + }) +``` + + + + +#### Websearch + +```js +const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat or cat'`, { + type: 'websearch', + config: 'english' + }) +``` + + + + + + +## Filter by TBD + + + + + +### Notes + +- `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work. + ```js + .filter('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains. + .filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column. + .filter('id','in','(6,7)') // Use Postgres list () for in filter. + .filter('id','in',`(${arr})`) // You can insert a javascript array. + ``` + + +### Examples + + + +#### With `select()` + +```js +const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .filter('name', 'in', '("Paris","Tokyo")') +``` + + + + +#### With `update()` + +```js +const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .filter('name', 'in', '("Paris","Tokyo")') +``` + + + + +#### With `delete()` + +```js +const { data, error } = await supabase + .from('cities') + .delete() + .filter('name', 'in', '("Paris","Tokyo")') +``` + + + + +#### With `rpc()` + +```js +// Only valid if the Postgres function returns a table type. +const { data, error } = await supabase + .rpc('echo_all_cities') + .filter('name', 'in', '("Paris","Tokyo")') +``` + + + + +#### Filter embedded resources + +```js +const { data, error } = await supabase + .from('cities') + .select('name, countries ( name )') + .filter('countries.name', 'in', '("France","Japan")') +``` + + + + diff --git a/spec/supabase_js_v1_sdk.yaml b/spec/supabase_js_v1_sdk.yaml index be09a629bd1..c64a2eed195 100644 --- a/spec/supabase_js_v1_sdk.yaml +++ b/spec/supabase_js_v1_sdk.yaml @@ -279,7 +279,8 @@ functions: description: | This method gets the user object from memory. examples: - - summary: Get the logged in user + - id: example-auth-user-get + summary: Get the logged in user code: | ```js const user = supabase.auth.user() @@ -512,7 +513,8 @@ functions: - Requires a `service_role` key. - This function should be called on a server. Never expose your `service_role` key in the browser. examples: - - summary: Remove a user completely. + - id: example-delete-user + summary: Remove a user completely. code: | ```js const { data: user, error } = await supabase.auth.api.deleteUser( @@ -701,8 +703,8 @@ functions: code: | ```js const { data: user, error } = await supabase.functions.invoke('hello', { - headers: { - "my-custom-header": 'my-custom-header-value' + headers: { + "my-custom-header": 'my-custom-header-value' }, body: JSON.stringify({ foo: 'bar' }) }) @@ -756,11 +758,11 @@ functions: - id: example-data-select-foreign-multiple summary: Query the same foreign table multiple times description: | - Sometimes you will need to query the same foreign table twice. - In this case, you can use the name of the joined column to identify - which join you intend to use. For convenience, you can also give an - alias for each column. For example, if we had a shop of products, - and we wanted to get the supplier and the purchaser at the same time + Sometimes you will need to query the same foreign table twice. + In this case, you can use the name of the joined column to identify + which join you intend to use. For convenience, you can also give an + alias for each column. For example, if we had a shop of products, + and we wanted to get the supplier and the purchaser at the same time (both in the users) table: code: | ```js @@ -775,7 +777,7 @@ functions: - id: example-data-select-inner summary: Filtering with inner joins description: | - If you want to filter a table based on a child table's values you can use the `!inner()` function. For example, if you wanted + If you want to filter a table based on a child table's values you can use the `!inner()` function. For example, if you wanted to select all rows in a `message` table which belong to a user with the `username` "Jane": code: | ```js @@ -798,10 +800,10 @@ functions: - id: example-data-select-json summary: Querying JSON data description: | - If you have data inside of a JSONB column, you can apply select - and query filters to the data values. Postgres offers a - [number of operators](https://www.postgresql.org/docs/current/functions-json.html) - for querying JSON data. Also see + If you have data inside of a JSONB column, you can apply select + and query filters to the data values. Postgres offers a + [number of operators](https://www.postgresql.org/docs/current/functions-json.html) + for querying JSON data. Also see [PostgREST docs](http://postgrest.org/en/v7.0.0/api.html#json-columns) for more details. code: | ```js @@ -857,7 +859,7 @@ functions: name: 'insert()' description: | - By default, every time you run `insert()`, the client library will make a `select` to return the full record. - This is convenient, but it can also cause problems if your Policies are not configured to allow the `select` operation. + This is convenient, but it can also cause problems if your Policies are not configured to allow the `select` operation. If you are using Row Level Security and you are encountering problems, try setting the `returning` param to `minimal`. examples: - id: example-data-create @@ -873,7 +875,7 @@ functions: - id: example-data-create-bulk summary: Bulk create description: | - When running a bulk create, the operation is handled in a single transaction. If any of the inserts fail, all other operations are + When running a bulk create, the operation is handled in a single transaction. If any of the inserts fail, all other operations are rolled back. code: | ```js @@ -887,10 +889,10 @@ functions: - id: example-data-create-upsert summary: Upsert description: | - For upsert, if set to true, primary key columns would need to be included - in the data parameter in order for an update to properly happen. Also, primary keys - used must be natural, not surrogate. There are however, - [workarounds](https://github.com/PostgREST/postgrest/issues/1118) + For upsert, if set to true, primary key columns would need to be included + in the data parameter in order for an update to properly happen. Also, primary keys + used must be natural, not surrogate. There are however, + [workarounds](https://github.com/PostgREST/postgrest/issues/1118) for surrogate primary keys. code: | ```js @@ -923,16 +925,16 @@ functions: - id: example-data-update-json summary: Updating JSON data description: | - Postgres offers a - [number of operators](https://www.postgresql.org/docs/current/functions-json.html) - for working with JSON data. Right now it is only possible to update an entire JSON document, + Postgres offers a + [number of operators](https://www.postgresql.org/docs/current/functions-json.html) + for working with JSON data. Right now it is only possible to update an entire JSON document, but we are [working on ideas](https://github.com/PostgREST/postgrest/issues/465) for updating individual keys. code: | ```js const { data, error } = await supabase .from('users') .update(` - address: { + address: { street: 'Melrose Place', postcode: 90210 } @@ -944,7 +946,7 @@ functions: summary: 'Upsert data into database' name: 'upsert()' description: | - - Primary keys should be included in the data payload in order for an update to work correctly. + - Primary keys should be included in the data payload in order for an update to work correctly. - Primary keys must be natural, not surrogate. There are however, [workarounds](https://github.com/PostgREST/postgrest/issues/1118) for surrogate primary keys. examples: - id: example-data-upsert-basic @@ -969,8 +971,8 @@ functions: - id: example-data-upsert-constraints summary: Upserting into tables with constraints description: | - Running the following will cause supabase to upsert data into the `users` table. - If the username 'supabot' already exists, the `onConflict` argument tells supabase to overwrite that row + Running the following will cause supabase to upsert data into the `users` table. + If the username 'supabot' already exists, the `onConflict` argument tells supabase to overwrite that row based on the column passed into `onConflict`. code: | ```js @@ -984,11 +986,11 @@ functions: ```js const { data, error, count } = await supabase .from('users') - .upsert({ - id: 3, message: 'foo', - username: 'supabot' - }, { - count: 'exact' + .upsert({ + id: 3, message: 'foo', + username: 'supabot' + }, { + count: 'exact' }) ``` @@ -1055,7 +1057,7 @@ functions: summary: With filters description: | Postgres functions that return tables can also be combined with - [Modifiers](/docs/reference/javascript/using-modifiers) and + [Modifiers](/docs/reference/javascript/using-modifiers) and [Filters](/docs/reference/javascript/using-filters). code: | ```js @@ -1118,8 +1120,8 @@ functions: - id: example-data-realtime-updates summary: Listening to updates description: | - By default, Supabase will send only the updated record. If you want to receive the previous values as well you can - enable full replication for the table you are listening too: + By default, Supabase will send only the updated record. If you want to receive the previous values as well you can + enable full replication for the table you are listening too: ```sql alter table "your_table" replica identity full; @@ -1136,8 +1138,8 @@ functions: - id: example-data-realtime-deletes summary: Listening to deletes description: | - By default, Supabase does not send deleted records. If you want to receive the deleted record you can - enable full replication for the table you are listening too: + By default, Supabase does not send deleted records. If you want to receive the deleted record you can + enable full replication for the table you are listening too: ```sql alter table "your_table" replica identity full; @@ -1218,7 +1220,7 @@ functions: name: 'listBuckets()' description: | - Policy permissions required: - - `buckets` permissions: `select` + - `buckets` permissions: `select` - `objects` permissions: none examples: - id: example-storage-list-buckets @@ -1230,1348 +1232,1434 @@ functions: .listBuckets() ``` - # - id: storage.getBucket(): - # summary: 'getBucket()' - # $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.getBucket' - # description: | - # - Policy permissions required: - # - `buckets` permissions: `select` - # - `objects` permissions: none - # examples: - # - summary: Get bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .getBucket('avatars') - # ``` - - # storage.createBucket(): - # summary: 'createBucket()' - # $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.createBucket' - # description: | - # - Policy permissions required: - # - `buckets` permissions: `insert` - # - `objects` permissions: none - # examples: - # - summary: Create bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .createBucket('avatars', { public: false }) - # ``` - - # storage.emptyBucket(): - # summary: 'emptyBucket()' - # $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.emptyBucket' - # description: | - # - Policy permissions required: - # - `buckets` permissions: `select` - # - `objects` permissions: `select` and `delete` - # examples: - # - summary: Empty bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .emptyBucket('avatars') - # ``` - # storage.updateBucket(): - # summary: 'updateBucket()' - # $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.updateBucket' - # description: | - # - Policy permissions required: - # - `buckets` permissions: `update` - # - `objects` permissions: none - # examples: - # - summary: Update bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .updateBucket('avatars', { public: false }) - # ``` - - # storage.deleteBucket(): - # summary: 'deleteBucket()' - # $ref: '@supabase/storage-js."lib/StorageBucketApi".StorageBucketApi.deleteBucket' - # description: | - # - Policy permissions required: - # - `buckets` permissions: `select` and `delete` - # - `objects` permissions: none - # examples: - # - summary: Delete bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .deleteBucket('avatars') - # ``` - - # storage.from.upload(): - # summary: 'from.upload()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.upload' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `insert` - # - For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Upload file using `ArrayBuffer` from base64 file data instead, see example below. - # examples: - # - summary: Upload file - # code: | - # ```js - # const avatarFile = event.target.files[0] - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .upload('public/avatar1.png', avatarFile, { - # cacheControl: '3600', - # upsert: false - # }) - # ``` - # - summary: Upload file using `ArrayBuffer` from base64 file data - # code: | - # ```js - # import { decode } from 'base64-arraybuffer' - - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .upload('public/avatar1.png', decode('base64FileData'), { - # contentType: 'image/png' - # }) - # ``` - - # storage.from.update(): - # summary: 'from.update()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.update' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `update` and `select` - # - For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Update file using `ArrayBuffer` from base64 file data instead, see example below. - # examples: - # - summary: Update file - # code: | - # ```js - # const avatarFile = event.target.files[0] - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .update('public/avatar1.png', avatarFile, { - # cacheControl: '3600', - # upsert: false - # }) - # ``` - # - summary: Update file using `ArrayBuffer` from base64 file data - # code: | - # ```js - # import {decode} from 'base64-arraybuffer' - - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .update('public/avatar1.png', decode('base64FileData'), { - # contentType: 'image/png' - # }) - # ``` - - # storage.from.move(): - # summary: 'from.move()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.move' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `update` and `select` - # examples: - # - summary: Move file - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .move('public/avatar1.png', 'private/avatar2.png') - # ``` - - # storage.from.copy(): - # summary: 'from.copy()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.copy' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `update` and `select` - # examples: - # - summary: Copy file - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .copy('public/avatar1.png', 'private/avatar2.png') - # ``` - - # storage.from.createSignedUrl(): - # summary: 'from.createSignedUrl()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.createSignedUrl' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `select` - # examples: - # - summary: Create Signed URL - # code: | - # ```js - # const { signedURL, error } = await supabase - # .storage - # .from('avatars') - # .createSignedUrl('folder/avatar1.png', 60) - # ``` - - # storage.from.createSignedUrls(): - # summary: 'from.createSignedUrls()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.createSignedUrls' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `select` - # examples: - # - summary: Create Signed URLs - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60) - # ``` - - # storage.from.getPublicUrl(): - # summary: 'from.getPublicUrl()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.getPublicUrl' - # description: | - # - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [app.supabase.com](https://app.supabase.com), clicking the overflow menu on a bucket and choosing "Make public" - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: none - # examples: - # - summary: Returns the URL for an asset in a public bucket - # code: | - # ```js - # const { publicURL, error } = supabase - # .storage - # .from('public-bucket') - # .getPublicUrl('folder/avatar1.png') - # ``` - - # storage.from.download(): - # summary: 'from.download()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.download' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `select` - # examples: - # - summary: Download file - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .download('folder/avatar1.png') - # ``` - - # storage.from.remove(): - # summary: 'from.remove()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.remove' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `delete` and `select` - # examples: - # - summary: Delete file - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .remove(['folder/avatar1.png']) - # ``` - - # storage.from.list(): - # summary: 'from.list()' - # $ref: '@supabase/storage-js."lib/StorageFileApi".StorageFileApi.list' - # description: | - # - Policy permissions required: - # - `buckets` permissions: none - # - `objects` permissions: `select` - # examples: - # - summary: List files in a bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .list('folder', { - # limit: 100, - # offset: 0, - # sortBy: { column: 'name', order: 'asc' }, - # }) - # ``` - # - summary: Search files in a bucket - # code: | - # ```js - # const { data, error } = await supabase - # .storage - # .from('avatars') - # .list('folder', { - # limit: 100, - # offset: 0, - # sortBy: { column: 'name', order: 'asc' }, - # search: 'jon' - # }) - # ``` - - # Using Modifiers: - # description: | - # Modifiers can be used on `select()` queries. - - # If a Postgres function returns a table response, you can also apply modifiers to the `rpc()` function. - - # limit(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.limit' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .limit(1) - # ``` - # - summary: With embedded resources - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, cities(name)') - # .eq('name', 'United States') - # .limit(1, { foreignTable: 'cities' }) - # ``` - - # order(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.order' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name', 'country_id') - # .order('id', { ascending: false }) - # ``` - # - summary: With embedded resources - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, cities(name)') - # .eq('name', 'United States') - # .order('name', {foreignTable: 'cities'}) - # ``` - - # range(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.range' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .range(0,3) - # ``` - - # single(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.single' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .limit(1) - # .single() - # ``` - - # maybeSingle(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.maybeSingle' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .eq('name', 'Singapore') - # .maybeSingle() - # ``` - - # Using Filters: - # description: | - # Filters can be used on `select()`, `update()`, and `delete()` queries. - - # If a Postgres function returns a table response, you can also apply filters. - - # ### Applying Filters - - # You must apply your filters to the end of your query. For example: - - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .eq('name', 'The Shire') // Correct - - # const { data, error } = await supabase - # .from('cities') - # .eq('name', 'The Shire') // Incorrect - # .select('name, country_id') - # ``` - - # ### Chaining - - # Filters can be chained together to produce advanced queries. For example: - - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .gte('population', 1000) - # .lt('population', 10000) - # ``` - - # ### Conditional Chaining - - # Filters can be built up one step at a time and then executed. For example: - - # ```js - # const filterByName = null - # const filterPopLow = 1000 - # const filterPopHigh = 10000 - - # let query = supabase - # .from('cities') - # .select('name, country_id') - - # if (filterByName) { query = query.eq('name', filterByName) } - # if (filterPopLow) { query = query.gte('population', filterPopLow) } - # if (filterPopHigh) { query = query.lt('population', filterPopHigh) } - - # const { data, error } = await query - # ``` - - # .or(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.or' - # description: | - # - `.or()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values. - - # ```js - # .or('id.in.(6,7), arraycol.cs.{"a","b"}') // Use Postgres list () for in filter. Array {} for array column and 'cs' for contains. - # .or(`id.in.(${arrList}),arraycol.cs.{${arr}}`) // You can insert a javascipt array for list or array on array column. - # .or(`id.in.(${arrList}),rangecol.cs.[${arrRange})`) // You can insert a javascipt array for list or range on a range column. - # ``` - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .or('id.eq.20,id.eq.30') - # ``` - # - summary: Use `or` with `and` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .or('id.gt.20,and(name.eq.New Zealand,name.eq.France)') - # ``` - # - summary: Use `or` on foreign tables - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('id, cities(*)') - # .or('name.eq.Wellington,name.eq.Paris', { foreignTable: "cities" }) - # ``` - - # .not(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.not' - # description: | - # - `.not()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values. - - # ```js - # .not('name','eq','Paris') - # .not('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains. - # .not('rangecol','cs','(1,2]') // Use Postgres range syntax for range column. - # .not('id','in','(6,7)') // Use Postgres list () for in filter. - # .not('id','in',`(${arr})`) // You can insert a javascript array. - # ``` - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .not('name', 'eq', 'Paris') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .not('name', 'eq', 'Paris') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .not('name', 'eq', 'Paris') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .not('name', 'eq', 'Paris') - # ``` - - # .match(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.match' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .match({name: 'Beijing', country_id: 156}) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .match({name: 'Beijing', country_id: 156}) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .match({name: 'Beijing', country_id: 156}) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .match({name: 'Beijing', country_id: 156}) - # ``` - - # .eq(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.eq' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .eq('name', 'The shire') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .eq('name', 'San Francisco') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .eq('name', 'Mordor') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .eq('name', 'San Francisco') - # ``` - - # .neq(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.neq' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .neq('name', 'The shire') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .neq('name', 'San Francisco') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .neq('name', 'Mordor') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .neq('name', 'Lagos') - # ``` - - # .gt(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.gt' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .gt('country_id', 250) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .gt('country_id', 250) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .gt('country_id', 250) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .gt('country_id', 250) - # ``` - - # .gte(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.gte' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .gte('country_id', 250) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .gte('country_id', 250) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .gte('country_id', 250) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .gte('country_id', 250) - # ``` - - # .lt(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.lt' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .lt('country_id', 250) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .lt('country_id', 250) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .lt('country_id', 250) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .lt('country_id', 250) - # ``` - - # .lte(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.lte' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .lte('country_id', 250) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .lte('country_id', 250) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .lte('country_id', 250) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .lte('country_id', 250) - # ``` - - # .like(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.like' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .like('name', '%la%') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .like('name', '%la%') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .like('name', '%la%') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .like('name', '%la%') - # ``` - - # .ilike(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.ilike' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .ilike('name', '%la%') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .ilike('name', '%la%') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .ilike('name', '%la%') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .ilike('name', '%la%') - # ``` - - # .is(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.is' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .is('name', null) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .is('name', null) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .is('name', null) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .is('name', null) - # ``` - - # .in(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.in' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .in('name', ['Rio de Janeiro', 'San Francisco']) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .in('name', ['Rio de Janeiro', 'San Francisco']) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .in('name', ['Rio de Janeiro', 'San Francisco']) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .in('name', ['Rio de Janeiro', 'San Francisco']) - # ``` - - # .contains(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.cs' - # description: | - # - `.contains()` can work on array columns or range columns. - # It is very useful for finding rows where a tag array contains all the values in the filter array. - - # ```js - # .contains('arraycol',["a","b"]) // You can use a javascript array for an array column - # .contains('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. - # .contains('rangecol','(1,2]') // Use Postgres range syntax for range column. - # .contains('rangecol',`(${arr}]`) // You can insert an array into a string. - # ``` - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, main_exports') - # .contains('main_exports', ['oil']) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .contains('main_exports', ['oil']) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .contains('main_exports', ['oil']) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .contains('main_exports', ['oil']) - # ``` - - # .containedBy(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.cd' - # description: | - # - `.containedBy()` can work on array columns or range columns. - - # ```js - # .containedBy('arraycol',["a","b"]) // You can use a javascript array for an array column - # .containedBy('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. - # .containedBy('rangecol','(1,2]') // Use Postgres range syntax for range column. - # .containedBy('rangecol',`(${arr}]`) // You can insert an array into a string. - # ``` - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, main_exports') - # .containedBy('main_exports', ['cars', 'food', 'machine']) - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .containedBy('main_exports', ['orks', 'surveillance', 'evil']) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .containedBy('main_exports', ['cars', 'food', 'machine']) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .containedBy('main_exports', ['cars', 'food', 'machine']) - # ``` - - # .rangeLt(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.sl' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, population_range_millions') - # .rangeLt('population_range_millions', '[150, 250]') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .rangeLt('population_range_millions', '[150, 250]') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .rangeLt('population_range_millions', '[150, 250]') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .rangeLt('population_range_millions', '[150, 250]') - # ``` - - # .rangeGt(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.sr' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, population_range_millions') - # .rangeGt('population_range_millions', '[150, 250]') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .rangeGt('population_range_millions', '[150, 250]') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .rangeGt('population_range_millions', '[150, 250]') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .rangeGt('population_range_millions', '[150, 250]') - # ``` - - # .rangeGte(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.nxl' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, population_range_millions') - # .rangeGte('population_range_millions', '[150, 250]') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .rangeGte('population_range_millions', '[150, 250]') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .rangeGte('population_range_millions', '[150, 250]') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .rangeGte('population_range_millions', '[150, 250]') - # ``` - - # .rangeLte(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.nxr' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, population_range_millions') - # .rangeLte('population_range_millions', '[150, 250]') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .rangeLte('population_range_millions', '[150, 250]') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .rangeLte('population_range_millions', '[150, 250]') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .rangeLte('population_range_millions', '[150, 250]') - # ``` - - # .rangeAdjacent(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.adj' - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, population_range_millions') - # .rangeAdjacent('population_range_millions', '[70, 185]') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .rangeAdjacent('population_range_millions', '[70, 185]') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .rangeAdjacent('population_range_millions', '[70, 185]') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .rangeAdjacent('population_range_millions', '[70, 185]') - # ``` - - # .overlaps(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.ov' - # description: | - # - `.overlaps()` can work on array columns or range columns. - - # ```js - # .overlaps('arraycol',["a","b"]) // You can use a javascript array for an array column - # .overlaps('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. - # .overlaps('rangecol','(1,2]') // Use Postgres range syntax for range column. - # .overlaps('rangecol',`(${arr}]`) // You can insert an array into a string. - # ``` - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .select('name, id, main_exports') - # .overlaps('main_exports', ['computers', 'minerals']) - # ``` - # - summary: With `update()` - # code: | - # ```js - # let countries = await supabase - # .from('countries') - # .update({ name: 'Mordor' }) - # .overlaps('main_exports', ['computers', 'minerals']) - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('countries') - # .delete() - # .overlaps('main_exports', ['computers', 'minerals']) - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_countries') - # .overlaps('main_exports', ['computers', 'minerals']) - # ``` - - # .textSearch(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.fts' - # examples: - # - summary: Text search - # code: | - # ```js - # const { data, error } = await supabase - # .from('quotes') - # .select('catchphrase') - # .textSearch('catchphrase', `'fat' & 'cat'`, { - # config: 'english' - # }) - # ``` - # - summary: Basic normalization - # description: Uses PostgreSQL's `plainto_tsquery` function. - # code: | - # ```js - # const { data, error } = await supabase - # .from('quotes') - # .select('catchphrase') - # .textSearch('catchphrase', `'fat' & 'cat'`, { - # type: 'plain', - # config: 'english' - # }) - # ``` - # - summary: Full normalization - # description: Uses PostgreSQL's `phraseto_tsquery` function. - # code: | - # ```js - # const { data, error } = await supabase - # .from('quotes') - # .select('catchphrase') - # .textSearch('catchphrase', `'fat' & 'cat'`, { - # type: 'phrase', - # config: 'english' - # }) - # ``` - # - summary: Websearch - # description: | - # Uses PostgreSQL's `websearch_to_tsquery` function. - # This function will never raise syntax errors, which makes it possible to use raw user-supplied input for search, and can be used - # with advanced operators. - - # - `unquoted text`: text not inside quote marks will be converted to terms separated by & operators, as if processed by plainto_tsquery. - # - `"quoted text"`: text inside quote marks will be converted to terms separated by <-> operators, as if processed by phraseto_tsquery. - # - `OR`: the word “or” will be converted to the | operator. - # - `-`: a dash will be converted to the ! operator. - - # code: | - # ```js - # const { data, error } = await supabase - # .from('quotes') - # .select('catchphrase') - # .textSearch('catchphrase', `'fat or cat'`, { - # type: 'websearch', - # config: 'english' - # }) - # ``` - - # .filter(): - # $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.filter' - # description: | - # - `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work. - # ```js - # .filter('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains. - # .filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column. - # .filter('id','in','(6,7)') // Use Postgres list () for in filter. - # .filter('id','in',`(${arr})`) // You can insert a javascript array. - # ``` - # examples: - # - summary: With `select()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, country_id') - # .filter('name', 'in', '("Paris","Tokyo")') - # ``` - # - summary: With `update()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .update({ name: 'Mordor' }) - # .filter('name', 'in', '("Paris","Tokyo")') - # ``` - # - summary: With `delete()` - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .delete() - # .filter('name', 'in', '("Paris","Tokyo")') - # ``` - # - summary: With `rpc()` - # code: | - # ```js - # // Only valid if the Postgres function returns a table type. - # const { data, error } = await supabase - # .rpc('echo_all_cities') - # .filter('name', 'in', '("Paris","Tokyo")') - # ``` - # - summary: Filter embedded resources - # code: | - # ```js - # const { data, error } = await supabase - # .from('cities') - # .select('name, countries ( name )') - # .filter('countries.name', 'in', '("France","Japan")') - # ``` + - id: function-storage-bucket-get + summary: 'Get a single bucket' + name: 'getBucket()' + description: | + - Policy permissions required: + - `buckets` permissions: `select` + - `objects` permissions: none + examples: + - id: example-storage-bucket-get + summary: Get bucket + code: | + ```js + const { data, error } = await supabase + .storage + .getBucket('avatars') + ``` + + - id: function-storage-bucket-create + summary: 'Create a new bucket' + name: 'createBucket()' + description: | + - Policy permissions required: + - `buckets` permissions: `insert` + - `objects` permissions: none + examples: + - id: example-storage-bucket-create + summary: Create bucket + code: | + ```js + const { data, error } = await supabase + .storage + .createBucket('avatars', { public: false }) + ``` + + - id: function-storate-bucket-empty + summary: 'Empty a bucket' + name: 'emptyBucket()' + description: | + - Policy permissions required: + - `buckets` permissions: `select` + - `objects` permissions: `select` and `delete` + examples: + - id: example-storage-bucket-empty + summary: Empty bucket + code: | + ```js + const { data, error } = await supabase + .storage + .emptyBucket('avatars') + ``` + - id: function-storage-bucket-update + summary: 'updateBucket()' + description: | + - Policy permissions required: + - `buckets` permissions: `update` + - `objects` permissions: none + examples: + - id: example-storage-bucket-update + summary: Update bucket + code: | + ```js + const { data, error } = await supabase + .storage + .updateBucket('avatars', { public: false }) + ``` + + - id: function-storage-bucket-delete + summary: 'deleteBucket()' + description: | + - Policy permissions required: + - `buckets` permissions: `select` and `delete` + - `objects` permissions: none + examples: + - id: example-storage-bucket-delete + summary: Delete bucket + code: | + ```js + const { data, error } = await supabase + .storage + .deleteBucket('avatars') + ``` + + - id: function-storage-upload + summary: 'Upload a file' + name: 'from.upload()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `insert` + - For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Upload file using `ArrayBuffer` from base64 file data instead, see example below. + examples: + - id: example-storage-file-upload + summary: Upload file + code: | + ```js + const avatarFile = event.target.files[0] + const { data, error } = await supabase + .storage + .from('avatars') + .upload('public/avatar1.png', avatarFile, { + cacheControl: '3600', + upsert: false + }) + ``` + - id: example-storage-file-upload-base64 + summary: Upload file using `ArrayBuffer` from base64 file data + code: | + ```js + import { decode } from 'base64-arraybuffer' + + const { data, error } = await supabase + .storage + .from('avatars') + .upload('public/avatar1.png', decode('base64FileData'), { + contentType: 'image/png' + }) + ``` + + - id: functions-storage-file-update + summary: 'Update a file' + name: 'storage.update()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `update` and `select` + - For React Native, using either `Blob`, `File` or `FormData` does not work as intended. Update file using `ArrayBuffer` from base64 file data instead, see example below. + examples: + - id: example-storage-file-update + summary: Update file + code: | + ```js + const avatarFile = event.target.files[0] + const { data, error } = await supabase + .storage + .from('avatars') + .update('public/avatar1.png', avatarFile, { + cacheControl: '3600', + upsert: false + }) + ``` + - id: example-storage-file-upload-base-64 + summary: Update file using `ArrayBuffer` from base64 file data + code: | + ```js + import {decode} from 'base64-arraybuffer' + + const { data, error } = await supabase + .storage + .from('avatars') + .update('public/avatar1.png', decode('base64FileData'), { + contentType: 'image/png' + }) + ``` + + - id: function-storage-file-move + summary: 'Move a file' + name: 'from.move()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `update` and `select` + examples: + - id: example-storage-file-move + summary: Move file + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .move('public/avatar1.png', 'private/avatar2.png') + ``` + + - id: function-storage-file-copy + summary: 'Copy a file' + name: 'from.copy()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `update` and `select` + examples: + - id: example-storage-file-copy + summary: Copy file + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .copy('public/avatar1.png', 'private/avatar2.png') + ``` + + - id: function-storage-signed-url + summary: 'Create a signed URL' + name: 'from.createSignedUrl()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + examples: + - id: example-storage-file-signed-url + summary: Create Signed URL + code: | + ```js + const { signedURL, error } = await supabase + .storage + .from('avatars') + .createSignedUrl('folder/avatar1.png', 60) + ``` + + - id: function-storage-signed-urls + summary: 'Sign multiple URLs' + name: 'storage.createSignedUrls()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + examples: + - id: example-storage-file-signed-urls + summary: Create Signed URLs + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60) + ``` + + - id: function-storage-public-url + summary: 'Get public URL' + name: 'from.getPublicUrl()' + description: | + - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [app.supabase.com](https://app.supabase.com), clicking the overflow menu on a bucket and choosing "Make public" + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: none + examples: + - id: example-storage-file-public + summary: Returns the URL for an asset in a public bucket + code: | + ```js + const { publicURL, error } = supabase + .storage + .from('public-bucket') + .getPublicUrl('folder/avatar1.png') + ``` + + - id: function-storage-download + summary: 'Download a file' + name: 'from.download()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + examples: + - id: example-storage-file-download + summary: Download file + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .download('folder/avatar1.png') + ``` + + - id: function-storage-file-remove + summary: 'from.remove()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `delete` and `select` + examples: + - id: example-storage-file-upload + summary: Delete file + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .remove(['folder/avatar1.png']) + ``` + + - id: function-storage-file-list + summary: 'List files' + name: 'from.list()' + description: | + - Policy permissions required: + - `buckets` permissions: none + - `objects` permissions: `select` + examples: + - id: example-storage-file-list + summary: List files in a bucket + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .list('folder', { + limit: 100, + offset: 0, + sortBy: { column: 'name', order: 'asc' }, + }) + ``` + - id: example-storage-file-search + summary: Search files in a bucket + code: | + ```js + const { data, error } = await supabase + .storage + .from('avatars') + .list('folder', { + limit: 100, + offset: 0, + sortBy: { column: 'name', order: 'asc' }, + search: 'jon' + }) + ``` + + - id: function-data-limit + summary: 'Limit rows returned' + name: 'limit()' + description: | + Modifiers can be used on `select()` queries. + + If a Postgres function returns a table response, you can also apply modifiers to the `rpc()` function. + examples: + - id: example-data-limit-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .limit(1) + ``` + - id: example-data-limit-embedded + summary: With embedded resources + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, cities(name)') + .eq('name', 'United States') + .limit(1, { foreignTable: 'cities' }) + ``` + + - id: function-data-order + summary: 'Order results' + name: 'order()' + examples: + - id: example-data-order-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name', 'country_id') + .order('id', { ascending: false }) + ``` + - id: example-data-order-embedded + summary: With embedded resources + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, cities(name)') + .eq('name', 'United States') + .order('name', {foreignTable: 'cities'}) + ``` + + - id: function-data-range + summary: 'Select a range of data' + name: 'range()' + examples: + - id: example-data-range-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .range(0,3) + ``` + + - id: function-data-single + summary: 'Get a single row of data' + name: 'single()' + examples: + - id: example-data-single-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .limit(1) + .single() + ``` + + - id: function-data-maybe-single + summary: 'Return a single row if it exists' + name: maybeSingle() + examples: + - id: example-data-maybe-single + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .eq('name', 'Singapore') + .maybeSingle() + ``` + + - id: function-filter-or + summary: 'Apply multiple filters with OR conditional' + name: .or() + description: | + - `.or()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values. + + ```js + .or('id.in.(6,7), arraycol.cs.{"a","b"}') // Use Postgres list () for in filter. Array {} for array column and 'cs' for contains. + .or(`id.in.(${arrList}),arraycol.cs.{${arr}}`) // You can insert a javascipt array for list or array on array column. + .or(`id.in.(${arrList}),rangecol.cs.[${arrRange})`) // You can insert a javascipt array for list or range on a range column. + ``` + examples: + - id: example-filter-or-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .or('id.eq.20,id.eq.30') + ``` + - id: example-filter-or-and + summary: Use `or` with `and` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .or('id.gt.20,and(name.eq.New Zealand,name.eq.France)') + ``` + - id: example-filter-or-select-foreign + summary: Use `or` on foreign tables + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('id, cities(*)') + .or('name.eq.Wellington,name.eq.Paris', { foreignTable: "cities" }) + ``` + + - id: function-filter-not + summary: 'Apply a "not" filter' + name: .not() + description: | + - `.not()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values. + + ```js + .not('name','eq','Paris') + .not('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains. + .not('rangecol','cs','(1,2]') // Use Postgres range syntax for range column. + .not('id','in','(6,7)') // Use Postgres list () for in filter. + .not('id','in',`(${arr})`) // You can insert a javascript array. + ``` + examples: + - id: example-filter-not-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .not('name', 'eq', 'Paris') + ``` + - id: example-filter-not-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .not('name', 'eq', 'Paris') + ``` + - id: example-filter-not-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .not('name', 'eq', 'Paris') + ``` + - id: example-filter-not-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .not('name', 'eq', 'Paris') + ``` + + - id: function-filter-match + summary: Match on several criteria + name: .match() + examples: + - id: example-filter-match-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .match({name: 'Beijing', country_id: 156}) + ``` + - id: example-filter-match-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .match({name: 'Beijing', country_id: 156}) + ``` + - id: example-filter-match-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .match({name: 'Beijing', country_id: 156}) + ``` + - id: example-filter-match-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .match({name: 'Beijing', country_id: 156}) + ``` + + - id: function-filter-eq + summary: Filter by exact equality + name: .eq() + examples: + - id: example-filter-eq-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .eq('name', 'The shire') + ``` + - id: example-filter-eq-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .eq('name', 'San Francisco') + ``` + - id: example-filter-eq-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .eq('name', 'Mordor') + ``` + - id: example-filter-eq-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .eq('name', 'San Francisco') + ``` + + - id: function-filter-neq + summary: Filter by not equal + name: .neq() + examples: + - id: example-filter-neq-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .neq('name', 'The shire') + ``` + - id: example-filter-neq-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .neq('name', 'San Francisco') + ``` + - id: example-filter-neq-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .neq('name', 'Mordor') + ``` + - id: example-filter-neq-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .neq('name', 'Lagos') + ``` + + - id: function-filter-gt + summary: Filter by greater than + name: .gt() + examples: + - id: example-filter-gt-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .gt('country_id', 250) + ``` + - id: example-filter-gt-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .gt('country_id', 250) + ``` + - id: example-filter-gt-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .gt('country_id', 250) + ``` + - id: example-filter-gt-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .gt('country_id', 250) + ``` + + - id: function-filter-gte + summary: Filter by greater than or equal + name: .gte() + examples: + - id: example-filter-gte-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .gte('country_id', 250) + ``` + - id: example-filter-gte-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .gte('country_id', 250) + ``` + - id: example-filter-gte-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .gte('country_id', 250) + ``` + - id: example-filter-gte-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .gte('country_id', 250) + ``` + + - id: function-filter-lt + summary: Filter by less than + name: .lt() + examples: + - id: example-filter-lt-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .lt('country_id', 250) + ``` + - id: example-filter-lt-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .lt('country_id', 250) + ``` + - id: example-filter-lt-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .lt('country_id', 250) + ``` + - id: example-filter-lt-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .lt('country_id', 250) + ``` + + - id: function-filter-lte + summary: Filter by TBD + name: .lte() + examples: + - id: example-filter-lte-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .lte('country_id', 250) + ``` + - id: example-filter-lte-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .lte('country_id', 250) + ``` + - id: example-filter-lte-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .lte('country_id', 250) + ``` + - id: example-filter-lte-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .lte('country_id', 250) + ``` + + - id: function-filter-like + summary: Filter by string equality + name: .like() + examples: + - id: example-filter-like-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .like('name', '%la%') + ``` + - id: example-filter-like-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .like('name', '%la%') + ``` + - id: example-filter-like-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .like('name', '%la%') + ``` + - id: example-filter-like-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .like('name', '%la%') + ``` + + - id: function-filter-ilike + summary: Filter by string equality (case insensitive) + name: .ilike() + examples: + - id: example-filter-ilike-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .ilike('name', '%la%') + ``` + - id: example-filter-ilike-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .ilike('name', '%la%') + ``` + - id: example-filter-ilike-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .ilike('name', '%la%') + ``` + - id: example-filter-ilike-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .ilike('name', '%la%') + ``` + + - id: function-filter-is + summary: Filter by null values + name: .is() + examples: + - id: example-filter-is-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .is('name', null) + ``` + - id: example-filter-is-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .is('name', null) + ``` + - id: example-filter-is-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .is('name', null) + ``` + - id: example-filter-is-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .is('name', null) + ``` + + - id: function-filter-in + summary: Filter if in array + name: .in() + examples: + - id: example-filter-in-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .in('name', ['Rio de Janeiro', 'San Francisco']) + ``` + - id: example-filter-in-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .in('name', ['Rio de Janeiro', 'San Francisco']) + ``` + - id: example-filter-in-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .in('name', ['Rio de Janeiro', 'San Francisco']) + ``` + - id: example-filter-in-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .in('name', ['Rio de Janeiro', 'San Francisco']) + ``` + + - id: function-filter-contains + summary: Filter if TBD + name: .contains() + description: | + - `.contains()` can work on array columns or range columns. + It is very useful for finding rows where a tag array contains all the values in the filter array. + + ```js + .contains('arraycol',["a","b"]) // You can use a javascript array for an array column + .contains('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. + .contains('rangecol','(1,2]') // Use Postgres range syntax for range column. + .contains('rangecol',`(${arr}]`) // You can insert an array into a string. + ``` + examples: + - id: example-filter-contains-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, main_exports') + .contains('main_exports', ['oil']) + ``` + - id: example-filter-contains-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .contains('main_exports', ['oil']) + ``` + - id: example-filter-contains-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .contains('main_exports', ['oil']) + ``` + - id: example-filter-contains-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .contains('main_exports', ['oil']) + ``` + + - id: function-filter-contained-by + summary: Filter by TBD + name: .containedBy() + description: | + - `.containedBy()` can work on array columns or range columns. + + ```js + .containedBy('arraycol',["a","b"]) // You can use a javascript array for an array column + .containedBy('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. + .containedBy('rangecol','(1,2]') // Use Postgres range syntax for range column. + .containedBy('rangecol',`(${arr}]`) // You can insert an array into a string. + ``` + examples: + - id: example-filter-contained-by-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, main_exports') + .containedBy('main_exports', ['cars', 'food', 'machine']) + ``` + - id: example-filter-contained-by-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .containedBy('main_exports', ['orks', 'surveillance', 'evil']) + ``` + - id: example-filter-contained-by-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .containedBy('main_exports', ['cars', 'food', 'machine']) + ``` + - id: example-filter-contained-by-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .containedBy('main_exports', ['cars', 'food', 'machine']) + ``` + + - id: function-filter-range-lt + summary: Filter by TBD + name: .rangeLt() + examples: + - id: example-filter-range-lt-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeLt('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-lt-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeLt('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-lt-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .rangeLt('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-lt-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeLt('population_range_millions', '[150, 250]') + ``` + + - id: function-filter-range-gt + summary: Filter by TBD + name: .rangeGt() + examples: + - id: example-filter-range-gt-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeGt('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-gt-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeGt('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-gt-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .rangeGt('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-gt-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeGt('population_range_millions', '[150, 250]') + ``` + + - id: function-filter-range-gte + summary: Filter by TBD + name: .rangeGte() + examples: + - id: example-filter-range-gte-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeGte('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-gte-udpdate + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeGte('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-gte-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .rangeGte('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-gte-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeGte('population_range_millions', '[150, 250]') + ``` + + - id: function-filter-range-lte + summary: Filter by TBD + name: .rangeLte() + examples: + - id: example-filter-range-lte-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeLte('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-lte-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeLte('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-lte-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .rangeLte('population_range_millions', '[150, 250]') + ``` + - id: example-filter-range-lte-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeLte('population_range_millions', '[150, 250]') + ``` + + - id: function-filter-range-adjacent + summary: Filter by TBD + name: .rangeAdjacent() + examples: + - id: example-filter-range-adjacent-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, population_range_millions') + .rangeAdjacent('population_range_millions', '[70, 185]') + ``` + - id: example-filter-range-adjacent-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .rangeAdjacent('population_range_millions', '[70, 185]') + ``` + - id: example-filter-range-adjacent-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .rangeAdjacent('population_range_millions', '[70, 185]') + ``` + - id: example-filter-range-adjacent-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .rangeAdjacent('population_range_millions', '[70, 185]') + ``` + + - id: function-filter-overlaps + summary: Filter by TBD + name: .overlaps() + description: | + - `.overlaps()` can work on array columns or range columns. + + ```js + .overlaps('arraycol',["a","b"]) // You can use a javascript array for an array column + .overlaps('arraycol','{"a","b"}') // You can use a string with Postgres array {} for array column. + .overlaps('rangecol','(1,2]') // Use Postgres range syntax for range column. + .overlaps('rangecol',`(${arr}]`) // You can insert an array into a string. + ``` + examples: + - id: example-filter-overlaps-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .select('name, id, main_exports') + .overlaps('main_exports', ['computers', 'minerals']) + ``` + - id: example-filter-overlaps-update + summary: With `update()` + code: | + ```js + let countries = await supabase + .from('countries') + .update({ name: 'Mordor' }) + .overlaps('main_exports', ['computers', 'minerals']) + ``` + - id: example-filter-overlaps-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('countries') + .delete() + .overlaps('main_exports', ['computers', 'minerals']) + ``` + - id: example-filter-overlaps-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_countries') + .overlaps('main_exports', ['computers', 'minerals']) + ``` + + - id: function-filter-search + summary: Filter by TBD + name: .textSearch() + examples: + - id: example-filter-search + summary: Text search + code: | + ```js + const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat' & 'cat'`, { + config: 'english' + }) + ``` + - id: example-filter-search-normalize + summary: Basic normalization + description: Uses PostgreSQL's `plainto_tsquery` function. + code: | + ```js + const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat' & 'cat'`, { + type: 'plain', + config: 'english' + }) + ``` + - id: example-filter-search-full-normalize + summary: Full normalization + description: Uses PostgreSQL's `phraseto_tsquery` function. + code: | + ```js + const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat' & 'cat'`, { + type: 'phrase', + config: 'english' + }) + ``` + - id: example-filter-search-websearch + summary: Websearch + description: | + Uses PostgreSQL's `websearch_to_tsquery` function. + This function will never raise syntax errors, which makes it possible to use raw user-supplied input for search, and can be used + with advanced operators. + + - `unquoted text`: text not inside quote marks will be converted to terms separated by & operators, as if processed by plainto_tsquery. + - `"quoted text"`: text inside quote marks will be converted to terms separated by <-> operators, as if processed by phraseto_tsquery. + - `OR`: the word “or” will be converted to the | operator. + - `-`: a dash will be converted to the ! operator. + + code: | + ```js + const { data, error } = await supabase + .from('quotes') + .select('catchphrase') + .textSearch('catchphrase', `'fat or cat'`, { + type: 'websearch', + config: 'english' + }) + ``` + + - id: function-filter-filter + summary: Filter by TBD + name: .filter() + description: | + - `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work. + ```js + .filter('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains. + .filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column. + .filter('id','in','(6,7)') // Use Postgres list () for in filter. + .filter('id','in',`(${arr})`) // You can insert a javascript array. + ``` + examples: + - id: example-filter-select + summary: With `select()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, country_id') + .filter('name', 'in', '("Paris","Tokyo")') + ``` + - id: example-filter-update + summary: With `update()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .update({ name: 'Mordor' }) + .filter('name', 'in', '("Paris","Tokyo")') + ``` + - id: example-filter-delete + summary: With `delete()` + code: | + ```js + const { data, error } = await supabase + .from('cities') + .delete() + .filter('name', 'in', '("Paris","Tokyo")') + ``` + - id: example-filter-rpc + summary: With `rpc()` + code: | + ```js + // Only valid if the Postgres function returns a table type. + const { data, error } = await supabase + .rpc('echo_all_cities') + .filter('name', 'in', '("Paris","Tokyo")') + ``` + - id: example-filter-embedded + summary: Filter embedded resources + code: | + ```js + const { data, error } = await supabase + .from('cities') + .select('name, countries ( name )') + .filter('countries.name', 'in', '("France","Japan")') + ```