ec86bbc4fe
Co-authored-by: Kang Ming <kang.ming1996@gmail.com> Co-authored-by: Joel Lee <lee.yi.jie.joel@gmail.com>
5511 lines
162 KiB
YAML
5511 lines
162 KiB
YAML
openref: 0.1
|
|
|
|
info:
|
|
id: reference/supabase-js
|
|
title: Supabase Client
|
|
description: |
|
|
|
|
Supabase JavaScript.
|
|
|
|
definition: ../../spec/enrichments/tsdoc_v2/combined.json
|
|
specUrl: https://github.com/supabase/supabase/edit/master/spec/supabase_js_v2.yml
|
|
slugPrefix: '/'
|
|
libraries:
|
|
- id: 'JavaScript'
|
|
version: '0.0.1'
|
|
|
|
functions:
|
|
- id: initializing
|
|
$ref: '@supabase/supabase-js.index.SupabaseClient.constructor'
|
|
description: |
|
|
You can initialize a new Supabase client using the `createClient()` method.
|
|
|
|
The Supabase client is your entrypoint to the rest of the Supabase functionality
|
|
and is the easiest way to interact with everything we offer within the Supabase ecosystem.
|
|
|
|
examples:
|
|
- id: create-client
|
|
name: createClient()
|
|
js: |
|
|
```js
|
|
import { createClient } from '@supabase/supabase-js'
|
|
|
|
// Create a single supabase client for interacting with your database
|
|
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')
|
|
```
|
|
response: |
|
|
{
|
|
"hello":"world"
|
|
}
|
|
- id: with-additional-parameters
|
|
name: With additional parameters
|
|
js: |
|
|
```js
|
|
import { createClient } from '@supabase/supabase-js'
|
|
|
|
const options = {
|
|
db: {
|
|
schema: 'public',
|
|
},
|
|
auth: {
|
|
autoRefreshToken: true,
|
|
persistSession: true,
|
|
detectSessionInUrl: true
|
|
},
|
|
global: {
|
|
headers: { 'x-my-custom-header': 'my-app-name' },
|
|
},
|
|
}
|
|
const supabase = createClient("https://xyzcompany.supabase.co", "public-anon-key", options)
|
|
```
|
|
response: |
|
|
{
|
|
"hello":"jonny"
|
|
}
|
|
- id: api-schemas
|
|
name: API schemas
|
|
js: |
|
|
```js
|
|
import { createClient } from '@supabase/supabase-js'
|
|
|
|
// Provide a custom schema. Defaults to "public".
|
|
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
|
|
db: { schema: 'other_schema' }
|
|
})
|
|
```
|
|
|
|
By default the API server points to the `public` schema. You can enable other database schemas within the Dashboard.
|
|
Go to `Settings > API > Schema` and add the schema which you want to expose to the API.
|
|
|
|
Note: each client connection can only access a single schema, so the code above can access the `other_schema` schema but cannot access the `public` schema.
|
|
- id: custom-fetch-implementation
|
|
name: Custom `fetch` implementation
|
|
js: |
|
|
```js
|
|
import { createClient } from '@supabase/supabase-js'
|
|
|
|
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
|
|
global: { fetch: fetch.bind(globalThis) }
|
|
})
|
|
```
|
|
|
|
`supabase-js` uses the [`cross-fetch`](https://www.npmjs.com/package/cross-fetch) library to make HTTP requests,
|
|
but an alternative `fetch` implementation can be provided as an option.
|
|
This is most useful in environments where `cross-fetch` is not compatible (for instance Cloudflare Workers).
|
|
- id: react-native-options
|
|
name: React Native options
|
|
js: |
|
|
```js
|
|
import 'react-native-url-polyfill/auto'
|
|
import { createClient } from '@supabase/supabase-js'
|
|
import AsyncStorage from "@react-native-async-storage/async-storage";
|
|
|
|
const supabase = createClient("https://xyzcompany.supabase.co", "public-anon-key", {
|
|
auth: {
|
|
storage: AsyncStorage,
|
|
autoRefreshToken: true,
|
|
persistSession: true,
|
|
detectSessionInUrl: false,
|
|
},
|
|
});
|
|
```
|
|
|
|
For React Native we recommend using `AsyncStorage` as the storage implementation for Supabase Auth.
|
|
- id: auth.signUp()
|
|
title: 'signUp()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.signUp'
|
|
notes: |
|
|
- By default, the user needs to verify their email address before logging in. To turn this off, disable **Confirm email** in [your project](https://supabase.com/dashboard/project/_/auth/providers).
|
|
- **Confirm email** determines if users need to confirm their email address after signing up.
|
|
- If **Confirm email** is enabled, a `user` is returned but `session` is null.
|
|
- If **Confirm email** is disabled, both a `user` and a `session` are returned.
|
|
- By default, when the user confirms their email address, they are redirected to the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls). You can modify your `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
|
|
- If signUp() is called for an existing confirmed user:
|
|
- When both **Confirm email** and **Confirm phone** (even when phone provider is disabled) are enabled in [your project](/dashboard/project/_/auth/providers), an obfuscated/fake user object is returned.
|
|
- When either **Confirm email** or **Confirm phone** (even when phone provider is disabled) is disabled, the error message, `User already registered` is returned.
|
|
- To fetch the currently logged-in user, refer to [`getUser()`](/docs/reference/javascript/auth-getuser).
|
|
examples:
|
|
- id: sign-up.
|
|
name: Sign up.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signUp({
|
|
email: 'example@email.com',
|
|
password: 'example-password',
|
|
})
|
|
```
|
|
- id: sign-up-with-additional-user-metadata.
|
|
name: Sign up with additional user metadata.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signUp(
|
|
{
|
|
email: 'example@email.com',
|
|
password: 'example-password',
|
|
options: {
|
|
data: {
|
|
first_name: 'John',
|
|
age: 27,
|
|
}
|
|
}
|
|
}
|
|
)
|
|
```
|
|
- id: auth.signInWithPassword()
|
|
title: 'signInWithPassword()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.signInWithPassword'
|
|
notes: |
|
|
- Requires either an email and password or a phone number and password.
|
|
examples:
|
|
- id: sign-in-with-email-and-password
|
|
name: Sign in with email and password
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithPassword({
|
|
email: 'example@email.com',
|
|
password: 'example-password',
|
|
})
|
|
```
|
|
- id: sign-in-with-phone-and-password
|
|
name: Sign in with phone and password
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithPassword({
|
|
phone: '+13334445555',
|
|
password: 'some-password',
|
|
})
|
|
|
|
// After receiving a SMS with a OTP.
|
|
const { data, error } = await supabase.auth.verifyOtp({
|
|
phone: '+13334445555',
|
|
token: '123456',
|
|
})
|
|
```
|
|
- id: auth.signInWithOtp()
|
|
title: 'signInWithOtp()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.signInWithOtp'
|
|
notes: |
|
|
- Requires either an email or phone number.
|
|
- This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
|
|
- If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
|
|
- If you're using phone, you can configure whether you want the user to receive a OTP.
|
|
- The magic link's destination URL is determined by the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls). You can modify the `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
|
|
examples:
|
|
- id: sign-in-with-email.
|
|
name: Sign in with email.
|
|
isSpotlight: true
|
|
description: The user will be sent an email which contains either a magiclink or a OTP or both. By default, a given user can only request a OTP once every 60 seconds.
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithOtp({
|
|
email: 'example@email.com',
|
|
})
|
|
```
|
|
- id: sign-in-with-sms-otp.
|
|
name: Sign in with SMS OTP.
|
|
isSpotlight: false
|
|
description: The user will be sent a SMS which contains a OTP. By default, a given user can only request a OTP once every 60 seconds.
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithOtp({
|
|
phone: '+13334445555',
|
|
})
|
|
```
|
|
- id: auth.signInWithOAuth()
|
|
title: 'signInWithOAuth()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.signInWithOAuth'
|
|
notes: |
|
|
- This method is used for signing in using a third-party provider.
|
|
- Supabase supports many different [third-party providers](https://supabase.com/docs/guides/auth#providers).
|
|
examples:
|
|
- id: sign-in-using-a-third-party-provider
|
|
name: Sign in using a third-party provider
|
|
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithOAuth({
|
|
provider: 'github'
|
|
})
|
|
```
|
|
- id: sign-in-using-a-third-party-provider-with-redirect
|
|
name: Sign in using a third-party provider with redirect
|
|
isSpotlight: false
|
|
description: |
|
|
When the third-party provider successfully authenticates the user, the provider will redirect the user to the URL specified in the `redirectTo` parameter. This parameter defaults to the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls). It does not redirect the user immediately after invoking this method.
|
|
You can modify the `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithOAuth({
|
|
provider: 'github',
|
|
options: {
|
|
redirectTo: 'https://example.com/welcome'
|
|
}
|
|
})
|
|
```
|
|
- id: sign-in-with-scopes
|
|
name: Sign in with scopes
|
|
isSpotlight: false
|
|
description: |
|
|
If you need additional data from an OAuth provider, you can include a space-separated list of scopes in your request to get back an OAuth provider token.
|
|
You may also need to specify the scopes in the provider's OAuth app settings, depending on the provider. The list of scopes will be documented by the third-party provider you are using and specifying scopes will enable you to use the OAuth provider token to call additional APIs supported by the third-party provider to get more information.
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.signInWithOAuth({
|
|
provider: 'github',
|
|
options: {
|
|
scopes: 'repo gist notifications'
|
|
}
|
|
})
|
|
const oAuthToken = data.session.provider_token // use to access provider API
|
|
```
|
|
- id: auth.signOut()
|
|
title: 'signOut()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.signOut'
|
|
notes: |
|
|
- In order to use the `signOut()` method, the user needs to be signed in first.
|
|
examples:
|
|
- id: sign-out
|
|
name: Sign out
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { error } = await supabase.auth.signOut()
|
|
```
|
|
- id: auth.verifyOtp()
|
|
title: 'verifyOtp()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.verifyOtp'
|
|
notes: |
|
|
- The `verifyOtp` method takes in different verification types. If a phone number is used, the type can either be `sms` or `phone_change`. If an email address is used, the type can be one of the following: `signup`, `magiclink`, `recovery`, `invite` or `email_change`.
|
|
- The verification type used should be determined based on the corresponding auth method called before `verifyOtp` to sign up / sign-in a user.
|
|
examples:
|
|
- id: verify-sms-one-time-password(otp)
|
|
name: Verify Sms One-Time Password (OTP)
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.verifyOtp({ phone, token, type: 'sms'})
|
|
```
|
|
- id: verify-signup-one-time-password(otp)
|
|
name: Verify Signup One-Time Password (OTP)
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.verifyOtp({ email, token, type: 'signup'})
|
|
```
|
|
- id: verify-email-auth(tokenhash)
|
|
name: Verify Email Auth (Token Hash)
|
|
isSpotlight: false
|
|
code: |
|
|
```js
|
|
const { data, error } = await supabase.auth.verifyOtp({ token_hash: tokenHash, type: 'email'})
|
|
```
|
|
- id: auth.getSession()
|
|
title: 'getSession()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.getSession'
|
|
examples:
|
|
- id: get-the-session-data
|
|
name: Get the session data
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.getSession()
|
|
```
|
|
- id: auth.getUser()
|
|
title: 'getUser()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.getUser'
|
|
notes: |
|
|
- This method gets the user object from the current session.
|
|
- Fetches the user object from the database instead of local session.
|
|
examples:
|
|
- id: get-the-logged-in-user-with-the-current-existing-session
|
|
name: Get the logged in user with the current existing session
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data: { user } } = await supabase.auth.getUser()
|
|
```
|
|
- id: get-the-logged-in-user-with-a-custom-access-token-jwt
|
|
name: Get the logged in user with a custom access token jwt.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data: { user } } = await supabase.auth.getUser(jwt)
|
|
```
|
|
- id: auth.updateUser()
|
|
title: 'updateUser()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.updateUser'
|
|
notes: |
|
|
- In order to use the `updateUser()` method, the user needs to be signed in first.
|
|
- By Default, email updates sends a confirmation link to both the user's current and new email.
|
|
To only send a confirmation link to the user's new email, disable **Secure email change** in your project's [email auth provider settings](https://supabase.com/dashboard/project/_/auth/providers).
|
|
examples:
|
|
- id: update-the-email-for-an-authenticated-user
|
|
name: Update the email for an authenticated user
|
|
description: Sends a "Confirm Email Change" email to the new email address.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.updateUser({email: 'new@email.com'})
|
|
```
|
|
- id: update-the-password-for-an-authenticated-user
|
|
name: Update the password for an authenticated user
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.updateUser({password: 'new password'})
|
|
```
|
|
- id: update-the-user's-metadata
|
|
name: Update the user's metadata
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.updateUser({
|
|
data: { hello: 'world' }
|
|
})
|
|
```
|
|
- id: auth.setSession()
|
|
title: 'setSession()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.setSession'
|
|
notes: |
|
|
- `setSession()` takes in a refresh token and uses it to get a new session.
|
|
- The refresh token can only be used once to obtain a new session.
|
|
- [Refresh token rotation](/docs/reference/auth/config#refresh_token_rotation_enabled) is enabled by default on all projects to guard against replay attacks.
|
|
- You can configure the [`REFRESH_TOKEN_REUSE_INTERVAL`](https://supabase.com/docs/reference/auth/config#refresh_token_reuse_interval) which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.
|
|
examples:
|
|
- id: refresh-the-session
|
|
name: Refresh the session
|
|
description: Sets the session data from refresh_token and returns current session or an error if the refresh_token is invalid.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = supabase.auth.setSession(refresh_token)
|
|
```
|
|
- id: auth.refreshSession()
|
|
title: 'refreshSession()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.refreshSession'
|
|
notes: |
|
|
- This method will refresh the session whether the current one is expired or not.
|
|
- Both examples destructure `user` and `session` from `data`. This is not required; so `const { data, error } =` is also valid.
|
|
examples:
|
|
- id: refresh-session-using-the-current-session
|
|
name: Refresh session using the current session
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data: { user, session }, error } = await supabase.auth.refreshSession()
|
|
```
|
|
- id: refresh-session-using-a-passed-in-session
|
|
name: Refresh session using a passed-in session
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data: { user, session }, error } = await supabase.auth.refreshSession({ refresh_token })
|
|
```
|
|
- id: auth.onAuthStateChange()
|
|
title: 'onAuthStateChange()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.onAuthStateChange'
|
|
notes: |
|
|
- Types of auth events: `SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `USER_UPDATED`, `USER_DELETED`, `PASSWORD_RECOVERY`
|
|
examples:
|
|
- id: listen-to-auth-changes
|
|
name: Listen to auth changes
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
console.log(event, session)
|
|
})
|
|
```
|
|
- id: listen-to-sign-in
|
|
name: Listen to sign in
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
if (event == 'SIGNED_IN') console.log('SIGNED_IN', session)
|
|
})
|
|
```
|
|
- id: listen-to-sign-out
|
|
name: Listen to sign out
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
if (event == 'SIGNED_OUT') console.log('SIGNED_OUT', session)
|
|
})
|
|
```
|
|
- id: listen-to-token-refresh
|
|
name: Listen to token refresh
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
if (event == 'TOKEN_REFRESHED') console.log('TOKEN_REFRESHED', session)
|
|
})
|
|
```
|
|
- id: listen-to-user-updates
|
|
name: Listen to user updates
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
if (event == 'USER_UPDATED') console.log('USER_UPDATED', session)
|
|
})
|
|
```
|
|
- id: listen-to-user-deleted
|
|
name: Listen to user deleted
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
if (event == 'USER_DELETED') console.log('USER_DELETED', session)
|
|
})
|
|
```
|
|
- id: listen-to-password-recovery-events
|
|
name: Listen to password recovery events
|
|
js: |
|
|
```js
|
|
supabase.auth.onAuthStateChange((event, session) => {
|
|
if (event == 'PASSWORD_RECOVERY') console.log('PASSWORD_RECOVERY', session)
|
|
})
|
|
```
|
|
- id: Supabase Auth Admin Api
|
|
title: 'Overview'
|
|
notes: |
|
|
- Any method under the `supabase.auth.admin` namespace requires a `service_role` key.
|
|
- These methods are considered admin methods and should be called on a trusted server. Never expose your `service_role` key in the browser.
|
|
|
|
- id: auth.admin.getUserById()
|
|
title: 'getUserById()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.getUserById'
|
|
notes: |
|
|
- Fetches the user object from the database based on the user's id.
|
|
- The `getUserById()` method requires the user's id which maps to the `auth.users.id` column.
|
|
examples:
|
|
- id: fetch-the-user-object-using-the-access-token-jwt
|
|
name: Fetch the user object using the access_token jwt.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.getUserById(1)
|
|
```
|
|
|
|
- id: auth.admin.listUsers()
|
|
title: 'listUsers()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.listUsers'
|
|
examples:
|
|
- id: get-a-full-list-of-users.
|
|
name: Get a full list of users.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data: { users }, error } = await supabase.auth.admin.listUsers()
|
|
```
|
|
- id: auth.admin.createUser()
|
|
title: 'createUser()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.createUser'
|
|
notes: |
|
|
- To confirm the user's email address or phone number, set `email_confirm` or `phone_confirm` to true. Both arguments default to false.
|
|
examples:
|
|
- id: create-a-new-user-with-custom-user-metadata
|
|
name: Create a new user with custom user metadata
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.createUser({
|
|
email: 'user@email.com',
|
|
password: 'password',
|
|
user_metadata: { name: 'Yoda' }
|
|
})
|
|
```
|
|
- id: auto-confirm-the-user's-email
|
|
name: Auto-confirm the user's email
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.createUser({
|
|
email: 'user@email.com',
|
|
email_confirm: true
|
|
})
|
|
```
|
|
- id: auto-confirm-the-user's-phone-number
|
|
name: Auto-confirm the user's phone number
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.createUser({
|
|
phone: '1234567890',
|
|
phone_confirm: true
|
|
})
|
|
```
|
|
- id: auth.admin.deleteUser()
|
|
title: 'deleteUser()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.deleteUser'
|
|
notes: |
|
|
- The `deleteUser()` method requires the user's ID, which maps to the `auth.users.id` column.
|
|
examples:
|
|
- id: removes-a-user
|
|
name: Removes a user
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.deleteUser(
|
|
'715ed5db-f090-4b8c-a067-640ecee36aa0'
|
|
)
|
|
```
|
|
|
|
- id: auth.admin.inviteUserByEmail()
|
|
title: 'inviteUserByEmail()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.inviteUserByEmail'
|
|
notes: |
|
|
- Sends an invite link to the user's email address.
|
|
examples:
|
|
- id: invite-a-user
|
|
name: Invite a user
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.inviteUserByEmail('email@example.com')
|
|
```
|
|
|
|
- id: auth.resetPasswordForEmail()
|
|
title: 'resetPasswordForEmail()'
|
|
$ref: '@supabase/gotrue-js.GoTrueClient.resetPasswordForEmail'
|
|
notes: |
|
|
Sends a password reset request to an email address.
|
|
When the user clicks the reset link in the email they are redirected back to your application.
|
|
Prompt the user for a new password and call `auth.updateUser()`:
|
|
```js
|
|
const { data, error } = await supabase.auth
|
|
.updateUser({ password: new_password })
|
|
```
|
|
examples:
|
|
- id: reset-password
|
|
name: Reset password
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.resetPasswordForEmail(email, {
|
|
redirectTo: 'https://example.com/update-password',
|
|
})
|
|
```
|
|
- id: reset-password(react)
|
|
name: Reset password (React)
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
/**
|
|
* Step 1: Send the user an email to get a password reset token.
|
|
* This email contains a link which sends the user back to your application.
|
|
*/
|
|
const { data, error } = await supabase.auth
|
|
.resetPasswordForEmail('user@email.com')
|
|
|
|
/**
|
|
* Step 2: Once the user is redirected back to your application,
|
|
* ask the user to reset their password.
|
|
*/
|
|
useEffect(() => {
|
|
supabase.auth.onAuthStateChange(async (event, session) => {
|
|
if (event == "PASSWORD_RECOVERY") {
|
|
const newPassword = prompt("What would you like your new password to be?");
|
|
const { data, error } = await supabase.auth
|
|
.updateUser({ password: newPassword })
|
|
|
|
if (data) alert("Password updated successfully!")
|
|
if (error) alert("There was an error updating your password.")
|
|
}
|
|
})
|
|
}, [])
|
|
```
|
|
|
|
- id: auth.admin.generateLink()
|
|
title: 'generateLink()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.generateLink'
|
|
examples:
|
|
- id: generate-a-signup-link
|
|
name: Generate a signup link
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.generateLink({
|
|
type: 'signup',
|
|
email: 'email@example.com',
|
|
options: {
|
|
'password': 'secret'
|
|
}
|
|
})
|
|
```
|
|
- id: generate-an-invite-link
|
|
name: Generate an invite link
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.generateLink({
|
|
type: 'invite',
|
|
email: 'email@example.com'
|
|
})
|
|
```
|
|
- id: generate-a-magic-link
|
|
name: Generate a magic link
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.generateLink({
|
|
type: 'magiclink',
|
|
email: 'email@example.com'
|
|
})
|
|
```
|
|
- id: generate-a-recovery-link
|
|
name: Generate a recovery link
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.auth.admin.generateLink({
|
|
type: 'recovery',
|
|
email: 'email@example.com'
|
|
})
|
|
```
|
|
- id: generate-links-to-change-current-email-address
|
|
name: Generate links to change current email address
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
// generate an email change link to be sent to the current email address
|
|
const { data, error } = await supabase.auth.admin.generateLink({
|
|
type: 'email_change_current',
|
|
email: 'current.email@example.com',
|
|
newEmail: 'new.email@example.com'
|
|
})
|
|
|
|
// generate an email change link to be sent to the new email address
|
|
const { data, error } = await supabase.auth.admin.generateLink({
|
|
type: 'email_change_new',
|
|
email: 'current.email@example.com',
|
|
newEmail: 'new.email@example.com'
|
|
})
|
|
```
|
|
|
|
- id: auth.admin.updateUserById()
|
|
title: 'updateUserById()'
|
|
$ref: '@supabase/gotrue-js.GoTrueAdminApi.updateUserById'
|
|
examples:
|
|
- id: updates-a-users-email.
|
|
name: Updates a user's email.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data: user, error } = await supabase.auth.admin.updateUserById(
|
|
'6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
|
|
{ email: 'new@email.com' }
|
|
)
|
|
```
|
|
- id: updates-a-users-password.
|
|
name: Updates a user's password.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data: user, error } = await supabase.auth.admin.updateUserById(
|
|
'6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
|
|
{ password: 'new_password' }
|
|
)
|
|
```
|
|
- id: updates-a-users-metadata.
|
|
name: Updates a user's metadata.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data: user, error } = await supabase.auth.admin.updateUserById(
|
|
'6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
|
|
{ user_metadata: { hello: 'world' } }
|
|
)
|
|
```
|
|
- id: updates-a-users-app-metadata.
|
|
name: Updates a user's app_metadata.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data: user, error } = await supabase.auth.admin.updateUserById(
|
|
'6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
|
|
{ app_metadata: { plan: 'trial' } }
|
|
)
|
|
```
|
|
- id: confirms-a-users-email-address.
|
|
name: Confirms a user's email address.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data: user, error } = await supabase.auth.admin.updateUserById(
|
|
'6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
|
|
{ email_confirm: true }
|
|
)
|
|
```
|
|
- id: confirms-a-users-phone-number.
|
|
name: Confirms a user's phone number.
|
|
isSpotlight: false
|
|
js: |
|
|
```js
|
|
const { data: user, error } = await supabase.auth.admin.updateUserById(
|
|
'6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
|
|
{ phone_confirm: true }
|
|
)
|
|
```
|
|
|
|
- id: select()
|
|
title: 'Fetching data'
|
|
description: 'This is the description'
|
|
$ref: '@supabase/postgrest-js.PostgrestQueryBuilder.select'
|
|
notes: |
|
|
- By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use `range()` queries to paginate through your data.
|
|
- `select()` can be combined with [Filters](/docs/reference/javascript/using-filters)
|
|
- `select()` can be combined with [Modifiers](/docs/reference/javascript/using-modifiers)
|
|
- `apikey` is a reserved keyword if you're using the [Supabase Platform](/docs/guides/platform) and [should be avoided as a column name](https://github.com/supabase/supabase/issues/5465).
|
|
examples:
|
|
- id: getting-your-data
|
|
name: Getting your data
|
|
data:
|
|
sql: |
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
tables:
|
|
- schema: public
|
|
name: countries
|
|
content: |
|
|
| name | id |
|
|
| :-----------------------|------:|
|
|
| Afghanistan | 1 |
|
|
| Albania | 2 |
|
|
| Algeria | 3 |
|
|
response: |
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Afghanistan"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
- id: selecting-specific-columns
|
|
name: Selecting specific columns
|
|
description: |
|
|
You can select specific fields from your tables.
|
|
data:
|
|
sql: |
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
tables:
|
|
- schema: public
|
|
name: countries
|
|
content: |
|
|
| name | id |
|
|
| :-----------------------|------:|
|
|
| Afghanistan | 1 |
|
|
| Albania | 2 |
|
|
| Algeria | 3 |
|
|
response: |
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Afghanistan"
|
|
},
|
|
{
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
hideCodeBlock: true
|
|
- id: query-foreign-tables
|
|
name: Query referenced tables
|
|
description: |
|
|
If your database has foreign key relationships, you can query related tables too.
|
|
code: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities (
|
|
name
|
|
)
|
|
`)
|
|
```
|
|
data:
|
|
sql: |
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Germany'),
|
|
(2, 'Indonesia');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 2, 'Bali'),
|
|
(2, 1, 'Munich');
|
|
tables:
|
|
- schema: public
|
|
name: countries
|
|
content: |
|
|
| name | id |
|
|
| :-----------------------|------:|
|
|
| Germany | 1 |
|
|
| Indonesia | 2 |
|
|
- schema: public
|
|
name: cities
|
|
content: |
|
|
| name | id |
|
|
| :-----------------------|------:|
|
|
| Bali | 1 |
|
|
| Munich | 2 |
|
|
response: |
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Germany",
|
|
"cities": [
|
|
{
|
|
"name": "Munich"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Indonesia",
|
|
"cities": [
|
|
{
|
|
"name": "Bali"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
|
|
- id: query-foreign-tables-through-a-join-table
|
|
name: Query referenced tables through a join table
|
|
data:
|
|
sql: |
|
|
create table
|
|
users (
|
|
id int8 primary key,
|
|
name text
|
|
);
|
|
create table
|
|
teams (
|
|
id int8 primary key,
|
|
name text
|
|
);
|
|
-- join table
|
|
create table
|
|
users_teams (
|
|
user_id int8 not null references users,
|
|
team_id int8 not null references teams,
|
|
-- both foreign keys must be part of a composite primary key
|
|
primary key (user_id, team_id)
|
|
);
|
|
|
|
insert into
|
|
users (id, name)
|
|
values
|
|
(1, 'Kiran'),
|
|
(2, 'Evan');
|
|
insert into
|
|
teams (id, name)
|
|
values
|
|
(1, 'Green'),
|
|
(2, 'Blue');
|
|
insert into
|
|
users_teams (user_id, team_id)
|
|
values
|
|
(1, 1),
|
|
(1, 2),
|
|
(2, 2);
|
|
response: |
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Kiran",
|
|
"teams": [
|
|
{
|
|
"name": "Green"
|
|
},
|
|
{
|
|
"name": "Blue"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Evan",
|
|
"teams": [
|
|
{
|
|
"name": "Blue"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
description: |
|
|
If you're in a situation where your tables are **NOT** directly
|
|
related, but instead are joined by a _join table_, you can still use
|
|
the `select()` method to query the related data. The join table needs
|
|
to have the foreign keys as part of its composite primary key.
|
|
code: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select(`
|
|
name,
|
|
teams (
|
|
name
|
|
)
|
|
`)
|
|
```
|
|
- id: query-the-same-foreign-table-multiple-times
|
|
name: Query the same referenced table multiple times
|
|
description: |
|
|
If you need to query the same referenced table twice, use the name of the
|
|
joined column to identify which join to use. You can also give each
|
|
column an alias.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (id int8 primary key, name text);
|
|
|
|
create table
|
|
messages (
|
|
sender_id int8 not null references users,
|
|
receiver_id int8 not null references users,
|
|
content text
|
|
);
|
|
|
|
insert into
|
|
users (id, name)
|
|
values
|
|
(1, 'Kiran'),
|
|
(2, 'Evan');
|
|
|
|
insert into
|
|
messages (sender_id, receiver_id, content)
|
|
values
|
|
(1, 2, '👋');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('messages')
|
|
.select(`
|
|
content,
|
|
from:sender_id(name),
|
|
to:receiver_id(name)
|
|
`)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"content": "👋",
|
|
"from": {
|
|
"name": "Kiran"
|
|
},
|
|
"to": {
|
|
"name": "Evan"
|
|
}
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: filtering-through-foreign-tables
|
|
name: Filtering through referenced tables
|
|
description: |
|
|
If the filter on a referenced table's column is not satisfied, the referenced
|
|
table returns `[]` or `null` but the parent table is not filtered out.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Germany'),
|
|
(2, 'Indonesia');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 2, 'Bali'),
|
|
(2, 1, 'Munich');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('cities')
|
|
.select('name, countries(*)')
|
|
.eq('countries.name', 'Estonia')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Bali",
|
|
"countries": null
|
|
},
|
|
{
|
|
"name": "Munich",
|
|
"countries": null
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
If you want to filter out the parent table rows, use the `!inner` hint:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('cities')
|
|
.select('name, countries!inner(*)')
|
|
.eq('countries.name', 'Estonia')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: querying-with-count-option
|
|
name: Querying with count option
|
|
description: |
|
|
You can get the number of rows by using the
|
|
[count](/docs/reference/javascript/select#parameters) option. For
|
|
example, to get the table count without returning all rows:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { count, error } = await supabase
|
|
.from('countries')
|
|
.select('*', { count: 'exact', head: true })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"count": 3,
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: querying-json-data
|
|
name: Querying JSON data
|
|
description: |
|
|
You can select and filter data inside of
|
|
[JSON](/docs/guides/database/json) columns. Postgres offers some
|
|
[operators](/docs/guides/database/json#query-the-jsonb-data) for
|
|
querying JSON data.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (
|
|
id int8 primary key,
|
|
name text,
|
|
address jsonb
|
|
);
|
|
|
|
insert into
|
|
users (id, name, address)
|
|
values
|
|
(1, 'Avdotya', '{"city":"Saint Petersburg"}');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select(`
|
|
id, name,
|
|
address->city
|
|
`)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Avdotya",
|
|
"city": "Saint Petersburg"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: insert()
|
|
title: 'Create data: insert()'
|
|
$ref: '@supabase/postgrest-js.PostgrestQueryBuilder.insert'
|
|
examples:
|
|
- id: create-a-record
|
|
name: Create a record
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.insert({ id: 1, name: 'Denmark' })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"status": 201,
|
|
"statusText": "Created"
|
|
}
|
|
```
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Denmark"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.insert({ id: 1, name: 'Denmark' })
|
|
```
|
|
- id: create-a-record-and-return-it
|
|
name: Create a record and return it
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.insert({ id: 1, name: 'Denmark' })
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Denmark"
|
|
}
|
|
],
|
|
"status": 201,
|
|
"statusText": "Created"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: bulk-create
|
|
name: Bulk create
|
|
description: |
|
|
A bulk create operation is handled in a single transaction.
|
|
If any of the inserts fail, none of the rows are inserted.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.insert([
|
|
{ id: 1, name: 'Nepal' },
|
|
{ id: 1, name: 'Vietnam' },
|
|
])
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "23505",
|
|
"details": "Key (id)=(1) already exists.",
|
|
"hint": null,
|
|
"message": "duplicate key value violates unique constraint \"countries_pkey\""
|
|
},
|
|
"status": 409,
|
|
"statusText": "Conflict"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: update()
|
|
title: 'Modify data: update()'
|
|
$ref: '@supabase/postgrest-js.PostgrestQueryBuilder.update'
|
|
notes: |
|
|
- `update()` should always be combined with [Filters](/docs/reference/javascript/using-filters) to target the item(s) you wish to update.
|
|
examples:
|
|
- id: updating-your-data
|
|
name: Updating your data
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Taiwan');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.update({ name: 'Australia' })
|
|
.eq('id', 1)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"status": 204,
|
|
"statusText": "No Content"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Australia"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.update({ name: 'Australia' })
|
|
.eq('id', 1)
|
|
```
|
|
- id: update-a-record-and-return-it
|
|
name: Update a record and return it
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Taiwan');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.update({ name: 'Australia' })
|
|
.eq('id', 1)
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Australia"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: updating-json-data
|
|
name: Updating JSON data
|
|
description: |
|
|
Postgres offers some
|
|
[operators](/docs/guides/database/json#query-the-jsonb-data) for
|
|
working with JSON data.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (
|
|
id int8 primary key,
|
|
name text,
|
|
address jsonb
|
|
);
|
|
|
|
insert into
|
|
users (id, name, address)
|
|
values
|
|
(1, 'Michael', '{ "postcode": 90210 }');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.update({
|
|
address: {
|
|
street: 'Melrose Place',
|
|
postcode: 90210
|
|
}
|
|
})
|
|
.eq('address->postcode', 90210)
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Michael",
|
|
"address": {
|
|
"street": "Melrose Place",
|
|
"postcode": 90210
|
|
}
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
Currently, it is only possible to update the entire JSON document.
|
|
hideCodeBlock: true
|
|
|
|
- id: upsert()
|
|
title: 'Upsert data: upsert()'
|
|
$ref: '@supabase/postgrest-js.PostgrestQueryBuilder.upsert'
|
|
notes: |
|
|
- Primary keys must be included in `values` to use upsert.
|
|
examples:
|
|
- id: upsert-your-data
|
|
name: Upsert your data
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.upsert({ id: 1, name: 'Albania' })
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 201,
|
|
"statusText": "Created"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.upsert({ id: 1, name: 'Albania' })
|
|
.select()
|
|
```
|
|
- id: bulk-upsert-your-data
|
|
name: Bulk Upsert your data
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.upsert([
|
|
{ id: 1, name: 'Albania' },
|
|
{ id: 2, name: 'Algeria' },
|
|
])
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 201,
|
|
"statusText": "Created"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: upserting-into-tables-with-constraints
|
|
name: Upserting into tables with constraints
|
|
description: |
|
|
In the following query, `upsert()` implicitly uses the `id`
|
|
(primary key) column to determine conflicts. If there is no existing
|
|
row with the same `id`, `upsert()` inserts a new row, which
|
|
will fail in this case as there is already a row with `handle` `"saoirse"`.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (
|
|
id int8 generated by default as identity primary key,
|
|
handle text not null unique,
|
|
display_name text
|
|
);
|
|
|
|
insert into
|
|
users (id, handle, display_name)
|
|
values
|
|
(1, 'saoirse', null);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.upsert({ id: 42, handle: 'saoirse', display_name: 'Saoirse' })
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "23505",
|
|
"details": "Key (handle)=(saoirse) already exists.",
|
|
"hint": null,
|
|
"message": "duplicate key value violates unique constraint \"users_handle_key\""
|
|
},
|
|
"status": 409,
|
|
"statusText": "Conflict"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
Using the `onConflict` option, you can instruct `upsert()` to use
|
|
another column with a unique constraint to determine conflicts:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
await supabase
|
|
.from('users')
|
|
.upsert(
|
|
{ id: 42, handle: 'saoirse', display_name: 'Saoirse' },
|
|
{ onConflict: 'handle' },
|
|
)
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 42,
|
|
"handle": "saoirse",
|
|
"display_name": "Saoirse"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: delete()
|
|
title: 'Delete data: delete()'
|
|
$ref: '@supabase/postgrest-js.PostgrestQueryBuilder.delete'
|
|
notes: |
|
|
- `delete()` should always be combined with [filters](/docs/reference/javascript/using-filters) to target the item(s) you wish to delete.
|
|
- If you use `delete()` with filters and you have
|
|
[RLS](/docs/learn/auth-deep-dive/auth-row-level-security) enabled, only
|
|
rows visible through `SELECT` policies are deleted. Note that by default
|
|
no rows are visible, so you need at least one `SELECT`/`ALL` policy that
|
|
makes the rows visible.
|
|
examples:
|
|
- id: delete-records
|
|
name: Delete records
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Spain');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.delete()
|
|
.eq('id', 1)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"status": 204,
|
|
"statusText": "No Content"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { error } = await supabase
|
|
.from('countries')
|
|
.delete()
|
|
.eq('id', 1)
|
|
```
|
|
|
|
- id: rpc()
|
|
title: 'Postgres functions: rpc()'
|
|
description: |
|
|
You can call Postgres functions as _Remote Procedure Calls_, logic in your database that you can execute from anywhere.
|
|
Functions are useful when the logic rarely changes—like for password resets and updates.
|
|
|
|
```sql
|
|
create or replace function hello_world() returns text as $$
|
|
select 'Hello world';
|
|
$$ language sql;
|
|
```
|
|
$ref: '@supabase/postgrest-js.PostgrestClient.rpc'
|
|
examples:
|
|
- id: call-a-postgres-function-without-arguments
|
|
name: Call a Postgres function without arguments
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create function hello_world() returns text as $$
|
|
select 'Hello world';
|
|
$$ language sql;
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase.rpc('hello_world')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": "Hello world",
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase.rpc('hello_world')
|
|
```
|
|
- id: call-a-postgres-function-with-arguments
|
|
name: Call a Postgres function with arguments
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create function echo(say text) returns text as $$
|
|
select say;
|
|
$$ language sql;
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase.rpc('echo', { say: '👋' })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": "👋",
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: bulk-processing
|
|
name: Bulk processing
|
|
description: |
|
|
You can process large payloads by passing in an array as an argument:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create function add_one_each(arr int[]) returns int[] as $$
|
|
select array_agg(n + 1) from unnest(arr) as n;
|
|
$$ language sql;
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase.rpc('add_one_each', { arr: [1, 2, 3] })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
2,
|
|
3,
|
|
4
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: call-a-postgres-function-with-filters
|
|
name: Call a Postgres function with filters
|
|
description: |
|
|
Postgres functions that return tables can also be combined with
|
|
[Filters](/docs/reference/javascript/using-filters) and
|
|
[Modifiers](/docs/reference/javascript/using-modifiers).
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'France'),
|
|
(2, 'United Kingdom');
|
|
|
|
create function list_stored_countries() returns setof countries as $$
|
|
select * from countries;
|
|
$$ language sql;
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.rpc('list_stored_countries')
|
|
.eq('id', 1)
|
|
.single()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"id": 1,
|
|
"name": "France"
|
|
},
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: Using Filters
|
|
description: |
|
|
Filters allow you to only return rows that match certain conditions.
|
|
|
|
Filters can be used on `select()`, `update()`, `upsert()`, and `delete()` queries.
|
|
|
|
If a Postgres function returns a table response, you can also apply filters.
|
|
|
|
### Applying Filters
|
|
|
|
Filters must be applied after any of `select()`, `update()`, `upsert()`,
|
|
`delete()`, and `rpc()` and before
|
|
[modifiers](/docs/reference/javascript/using-modifiers).
|
|
|
|
```ts
|
|
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,
|
|
to query cities with population between 1,000 and 10,000:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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
|
|
```
|
|
|
|
### Filter by values within a JSON column
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (
|
|
id int8 primary key,
|
|
name text,
|
|
address jsonb
|
|
);
|
|
|
|
insert into
|
|
users (id, name, address)
|
|
values
|
|
(1, 'Michael', '{ "postcode": 90210 }'),
|
|
(2, 'Jane', null);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select()
|
|
.eq('address->postcode', 90210)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Michael",
|
|
"address": {
|
|
"postcode": 90210
|
|
}
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
### Filter Referenced Tables
|
|
|
|
You can filter on referenced tables in your `select()` query using dot
|
|
notation:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Germany'),
|
|
(2, 'Indonesia');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 2, 'Bali'),
|
|
(2, 1, 'Munich');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities!inner (
|
|
name
|
|
)
|
|
`)
|
|
.eq('cities.name', 'Bali')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Indonesia",
|
|
"cities": [
|
|
{
|
|
"name": "Bali"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
- id: eq()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.eq'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.eq('name', 'Albania')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.eq('name', 'Albania')
|
|
```
|
|
|
|
- id: neq()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.neq'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.neq('name', 'Albania')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Afghanistan"
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.neq('name', 'Albania')
|
|
```
|
|
|
|
- id: gt()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.gt'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.gt('id', 2)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.gt('id', 2)
|
|
```
|
|
|
|
- id: gte()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.gte'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.gte('id', 2)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.gte('id', 2)
|
|
```
|
|
|
|
- id: lt()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.lt'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.lt('id', 2)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Afghanistan"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.lt('id', 2)
|
|
```
|
|
|
|
- id: lte()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.lte'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.lte('id', 2)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Afghanistan"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.lte('id', 2)
|
|
```
|
|
|
|
- id: like()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.like'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.like('name', '%Alba%')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.like('name', '%Alba%')
|
|
```
|
|
|
|
- id: ilike()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.ilike'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.like('name', '%alba%')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.like('name', '%alba%')
|
|
```
|
|
|
|
- id: is()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.is'
|
|
examples:
|
|
- id: checking-nullness
|
|
name: Checking nullness
|
|
description: |
|
|
Using the `eq()` filter doesn't work when filtering for `null`:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'null'),
|
|
(2, null);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.eq('name', null)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "null"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
Instead, you need to use `is()`:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.is('name', null)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"name": null
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.is('name', null)
|
|
```
|
|
|
|
- id: in()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.in'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.in('name', ['Albania', 'Algeria'])
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.in('name', ['Albania', 'Algeria'])
|
|
```
|
|
|
|
- id: contains()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.contains'
|
|
examples:
|
|
- id: on-array-columns
|
|
name: On array columns
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
issues (
|
|
id int8 primary key,
|
|
title text,
|
|
tags text[]
|
|
);
|
|
|
|
insert into
|
|
issues (id, title, tags)
|
|
values
|
|
(1, 'Cache invalidation is not working', array['is:open', 'severity:high', 'priority:low']),
|
|
(2, 'Use better names', array['is:open', 'severity:low', 'priority:medium']);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('issues')
|
|
.select('title')
|
|
.contains('tags', ['is:open', 'severity:high'])
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"title": "Cache invalidation is not working"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select()
|
|
.contains('name', ['is:online', 'faction:red'])
|
|
```
|
|
- id: on-range-columns
|
|
name: On range columns
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.contains('during', '[2000-01-01 13:00, 2000-01-01 13:30)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"room_name": "Emerald",
|
|
"during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: on`jsonb`columns
|
|
name: On `jsonb` columns
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (
|
|
id int8 primary key,
|
|
name text,
|
|
address jsonb
|
|
);
|
|
|
|
insert into
|
|
users (id, name, address)
|
|
values
|
|
(1, 'Michael', '{ "postcode": 90210, "street": "Melrose Place" }'),
|
|
(2, 'Jane', '{}');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select('name')
|
|
.contains('address', { postcode: 90210 })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Michael"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: containedBy()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.containedBy'
|
|
examples:
|
|
- id: on-array-columns
|
|
name: On array columns
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
classes (
|
|
id int8 primary key,
|
|
name text,
|
|
days text[]
|
|
);
|
|
|
|
insert into
|
|
classes (id, name, days)
|
|
values
|
|
(1, 'Chemistry', array['monday', 'friday']),
|
|
(2, 'History', array['monday', 'wednesday', 'thursday']);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('classes')
|
|
.select('name')
|
|
.containedBy('days', ['monday', 'tuesday', 'wednesday', 'friday'])
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Chemistry"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('classes')
|
|
.select('name')
|
|
.containedBy('days', ['monday', 'tuesday', 'wednesday', 'friday'])
|
|
```
|
|
- id: on-range-columns
|
|
name: On range columns
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.containedBy('during', '[2000-01-01 00:00, 2000-01-01 23:59)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"room_name": "Emerald",
|
|
"during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: on`jsonb`columns
|
|
name: On `jsonb` columns
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
users (
|
|
id int8 primary key,
|
|
name text,
|
|
address jsonb
|
|
);
|
|
|
|
insert into
|
|
users (id, name, address)
|
|
values
|
|
(1, 'Michael', '{ "postcode": 90210, "street": "Melrose Place" }'),
|
|
(2, 'Jane', '{}');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('users')
|
|
.select('name')
|
|
.containedBy('address', {})
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Jane"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: rangeGt()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeGt'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeGt('during', '[2000-01-02 08:00, 2000-01-02 09:00)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"room_name": "Topaz",
|
|
"during": "[\"2000-01-02 09:00:00\",\"2000-01-02 10:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeGt('during', '[2000-01-02 08:00, 2000-01-02 09:00)')
|
|
```
|
|
|
|
- id: rangeGte()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeGte'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeGte('during', '[2000-01-02 08:30, 2000-01-02 09:30)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 2,
|
|
"room_name": "Topaz",
|
|
"during": "[\"2000-01-02 09:00:00\",\"2000-01-02 10:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeGte('during', '[2000-01-02 08:30, 2000-01-02 09:30)')
|
|
```
|
|
|
|
- id: rangeLt()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeLt'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeLt('during', '[2000-01-01 15:00, 2000-01-01 16:00)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"room_name": "Emerald",
|
|
"during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeLt('during', '[2000-01-01 15:00, 2000-01-01 16:00)')
|
|
```
|
|
|
|
- id: rangeLte()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeLte'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeLte('during', '[2000-01-01 14:00, 2000-01-01 16:00)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"room_name": "Emerald",
|
|
"during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeLte('during', '[2000-01-01 14:00, 2000-01-01 16:00)')
|
|
```
|
|
|
|
- id: rangeAdjacent()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.rangeAdjacent'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeAdjacent('during', '[2000-01-01 12:00, 2000-01-01 13:00)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"room_name": "Emerald",
|
|
"during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.rangeAdjacent('during', '[2000-01-01 12:00, 2000-01-01 13:00)')
|
|
```
|
|
|
|
- id: overlaps()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.overlaps'
|
|
examples:
|
|
- id: on-array-columns
|
|
name: On array columns
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
issues (
|
|
id int8 primary key,
|
|
title text,
|
|
tags text[]
|
|
);
|
|
|
|
insert into
|
|
issues (id, title, tags)
|
|
values
|
|
(1, 'Cache invalidation is not working', array['is:open', 'severity:high', 'priority:low']),
|
|
(2, 'Use better names', array['is:open', 'severity:low', 'priority:medium']);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('issues')
|
|
.select('title')
|
|
.overlaps('tags', ['is:closed', 'severity:high'])
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"title": "Cache invalidation is not working"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('issues')
|
|
.select('title')
|
|
.overlaps('tags', ['is:closed', 'severity:high'])
|
|
```
|
|
- id: on-range-columns
|
|
name: On range columns
|
|
description: |
|
|
Postgres supports a number of [range
|
|
types](https://www.postgresql.org/docs/current/rangetypes.html). You
|
|
can filter on range columns using the string representation of range
|
|
values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
reservations (
|
|
id int8 primary key,
|
|
room_name text,
|
|
during tsrange
|
|
);
|
|
|
|
insert into
|
|
reservations (id, room_name, during)
|
|
values
|
|
(1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
|
|
(2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('reservations')
|
|
.select()
|
|
.overlaps('during', '[2000-01-01 12:45, 2000-01-01 13:15)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"room_name": "Emerald",
|
|
"during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
# TODO: schema & result
|
|
- id: textSearch()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.textSearch'
|
|
notes:
|
|
- For more information, see [Postgres full text search](/docs/guides/database/full-text-search).
|
|
examples:
|
|
- id: text-search
|
|
name: Text search
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('quotes')
|
|
.select('catchphrase')
|
|
.textSearch('catchphrase', `'fat' & 'cat'`, {
|
|
config: 'english'
|
|
})
|
|
```
|
|
- id: basic-normalization
|
|
name: Basic normalization
|
|
description: Uses PostgreSQL's `plainto_tsquery` function.
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('quotes')
|
|
.select('catchphrase')
|
|
.textSearch('catchphrase', `'fat' & 'cat'`, {
|
|
type: 'plain',
|
|
config: 'english'
|
|
})
|
|
```
|
|
- id: full-normalization
|
|
name: Full normalization
|
|
description: Uses PostgreSQL's `phraseto_tsquery` function.
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('quotes')
|
|
.select('catchphrase')
|
|
.textSearch('catchphrase', `'fat' & 'cat'`, {
|
|
type: 'phrase',
|
|
config: 'english'
|
|
})
|
|
```
|
|
- id: websearch
|
|
name: 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.
|
|
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('quotes')
|
|
.select('catchphrase')
|
|
.textSearch('catchphrase', `'fat or cat'`, {
|
|
type: 'websearch',
|
|
config: 'english'
|
|
})
|
|
```
|
|
|
|
- id: match()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.match'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.match({ id: 2, name: 'Albania' })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.match({ id: 2, name: 'Albania' })
|
|
```
|
|
|
|
- id: not()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.not'
|
|
notes: |
|
|
not() expects you to use the raw PostgREST syntax for the filter values.
|
|
|
|
```ts
|
|
.not('id', 'in', '(5,6,7)') // Use `()` for `in` filter
|
|
.not('arraycol', 'cs', '{"a","b"}') // Use `cs` for `contains()`, `{}` for array values
|
|
```
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'null'),
|
|
(2, null);
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.not('name', 'is', null)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "null"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.not('name', 'is', null)
|
|
```
|
|
|
|
- id: or()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.or'
|
|
notes: |
|
|
or() expects you to use the raw PostgREST syntax for the filter names and values.
|
|
|
|
```ts
|
|
.or('id.in.(5,6,7), arraycol.cs.{"a","b"}') // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
|
|
.or('id.in.(5,6,7), arraycol.cd.{"a","b"}') // Use `cd` for `containedBy()`
|
|
```
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.or('id.eq.2,name.eq.Algeria')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.or('id.eq.2,name.eq.Algeria')
|
|
```
|
|
- id: use`or`with`and`
|
|
name: Use `or` with `and`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.or('id.gt.3,and(id.eq.1,name.eq.Afghanistan)')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Afghanistan"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
- id: use`or`on-foreign-tables
|
|
name: Use `or` on referenced tables
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Germany'),
|
|
(2, 'Indonesia');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 2, 'Bali'),
|
|
(2, 1, 'Munich');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities!inner (
|
|
name
|
|
)
|
|
`)
|
|
.or('country_id.eq.1,name.eq.Beijing', { foreignTable: 'cities' })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Germany",
|
|
"cities": [
|
|
{
|
|
"name": "Munich"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: filter()
|
|
$ref: '@supabase/postgrest-js.PostgrestFilterBuilder.filter'
|
|
notes: |
|
|
filter() expects you to use the raw PostgREST syntax for the filter values.
|
|
|
|
```ts
|
|
.filter('id', 'in', '(5,6,7)') // Use `()` for `in` filter
|
|
.filter('arraycol', 'cs', '{"a","b"}') // Use `cs` for `contains()`, `{}` for array values
|
|
```
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.filter('name', 'in', '("Algeria","Japan")')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.filter('name', 'in', '("Algeria","Japan")')
|
|
```
|
|
- id: on-a-foreign-table
|
|
name: On a referenced table
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Germany'),
|
|
(2, 'Indonesia');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 2, 'Bali'),
|
|
(2, 1, 'Munich');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities!inner (
|
|
name
|
|
)
|
|
`)
|
|
.filter('cities.name', 'eq', 'Bali')
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Indonesia",
|
|
"cities": [
|
|
{
|
|
"name": "Bali"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities!inner (
|
|
name
|
|
)
|
|
`)
|
|
.filter('cities.name', 'eq', 'Bali')
|
|
```
|
|
|
|
- id: Using Modifiers
|
|
description: |
|
|
Filters work on the row level—they allow you to return rows that
|
|
only match certain conditions without changing the shape of the rows.
|
|
Modifiers are everything that don't fit that definition—allowing you to
|
|
change the format of the response (e.g., returning a CSV string).
|
|
|
|
Modifiers must be specified after filters. Some modifiers only apply for
|
|
queries that return rows (e.g., `select()` or `rpc()` on a function that
|
|
returns a table response).
|
|
|
|
- id: db.modifiers.select()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.select'
|
|
title: select()
|
|
examples:
|
|
- id: with`upsert()`
|
|
name: With `upsert()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.upsert({ id: 1, name: 'Albania' })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"status": 201,
|
|
"statusText": "Created"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.upsert({ id: 1, name: 'Algeria' })
|
|
.select()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Algeria"
|
|
}
|
|
],
|
|
"status": 201,
|
|
"statusText": "Created"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.upsert({ id: 1, name: 'Algeria' })
|
|
.select()
|
|
```
|
|
|
|
- id: order()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.order'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.order('name', { ascending: false })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 3,
|
|
"name": "Algeria"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Albania"
|
|
},
|
|
{
|
|
"id": 1,
|
|
"name": "Afghanistan"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('cities')
|
|
.select('name', 'country_id')
|
|
.order('id', { ascending: false })
|
|
```
|
|
- id: on-a-foreign-table
|
|
name: On a referenced table
|
|
description: |
|
|
Ordering on referenced tables doesn't affect the ordering of
|
|
the parent table.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'United States'),
|
|
(2, 'Vanuatu');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 1, 'Atlanta'),
|
|
(2, 1, 'New York City');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities (
|
|
name
|
|
)
|
|
`)
|
|
.order('name', { foreignTable: 'cities', ascending: false })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "United States",
|
|
"cities": [
|
|
{
|
|
"name": "New York City"
|
|
},
|
|
{
|
|
"name": "Atlanta"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Vanuatu",
|
|
"cities": []
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: limit()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.limit'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.limit(1)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Afghanistan"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.limit(1)
|
|
```
|
|
- id: on-a-foreign-table
|
|
name: On a referenced table
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
create table
|
|
cities (
|
|
id int8 primary key,
|
|
country_id int8 not null references countries,
|
|
name text
|
|
);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'United States');
|
|
insert into
|
|
cities (id, country_id, name)
|
|
values
|
|
(1, 1, 'Atlanta'),
|
|
(2, 1, 'New York City');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select(`
|
|
name,
|
|
cities (
|
|
name
|
|
)
|
|
`)
|
|
.limit(1, { foreignTable: 'cities' })
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "United States",
|
|
"cities": [
|
|
{
|
|
"name": "Atlanta"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
|
|
- id: range()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.range'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.range(0, 1)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "Afghanistan"
|
|
},
|
|
{
|
|
"name": "Albania"
|
|
}
|
|
],
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.range(0, 1)
|
|
```
|
|
|
|
- id: db.abortSignal()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.abortSignal'
|
|
title: abortSignal()
|
|
examples:
|
|
- id: aborting-requests-in-flight
|
|
name: Aborting requests in-flight
|
|
description: |
|
|
You can use an [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) to abort requests. Note that `status` and `statusText` don't mean anything for aborted requests as the request wasn't fulfilled.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="js">
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const ac = new AbortController()
|
|
ac.abort()
|
|
const { data, error } = await supabase
|
|
.from('very_big_table')
|
|
.select()
|
|
.abortSignal(ac.signal)
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"message": "FetchError: The user aborted a request.",
|
|
"details": "",
|
|
"hint": "",
|
|
"code": ""
|
|
},
|
|
"status": 400,
|
|
"statusText": "Bad Request"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const ac = new AbortController()
|
|
ac.abort()
|
|
const { data, error } = await supabase
|
|
.from('very_big_table')
|
|
.select()
|
|
.abortSignal(ac.signal)
|
|
```
|
|
|
|
- id: single()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.single'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.limit(1)
|
|
.single()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"name": "Afghanistan"
|
|
},
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select('name')
|
|
.limit(1)
|
|
.single()
|
|
```
|
|
|
|
- id: maybeSingle()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.maybeSingle'
|
|
examples:
|
|
- id: with`select()`
|
|
name: With `select()`
|
|
description: |
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.eq('name', 'Singapore')
|
|
.maybeSingle()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.eq('name', 'Singapore')
|
|
.maybeSingle()
|
|
```
|
|
|
|
- id: db.csv()
|
|
$ref: '@supabase/postgrest-js.PostgrestTransformBuilder.csv'
|
|
title: csv()
|
|
examples:
|
|
- id: return-data-as-csv
|
|
name: Return data as CSV
|
|
description: |
|
|
By default, the data is returned in JSON format, but can also be returned as Comma Separated Values.
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="schema">
|
|
<TabPanel id="schema" label="Schema">
|
|
|
|
```sql
|
|
create table
|
|
countries (id int8 primary key, name text);
|
|
|
|
insert into
|
|
countries (id, name)
|
|
values
|
|
(1, 'Afghanistan'),
|
|
(2, 'Albania'),
|
|
(3, 'Algeria');
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.csv()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="result" label="Result">
|
|
|
|
```json
|
|
{
|
|
"data": "id,name\n1,Afghanistan\n2,Albania\n3,Algeria",
|
|
"status": 200,
|
|
"statusText": "OK"
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
hideCodeBlock: true
|
|
isSpotlight: true
|
|
js: |
|
|
```ts
|
|
const { data, error } = await supabase
|
|
.from('countries')
|
|
.select()
|
|
.csv()
|
|
```
|
|
|
|
# NOTE: Not available on currently deployed PostgREST
|
|
# db.geojson():
|
|
# $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.geojson'
|
|
# title: geojson()
|
|
|
|
# NOTE: Not available on currently deployed PostgREST
|
|
# db.explain():
|
|
# $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.explain'
|
|
# title: explain()
|
|
|
|
# NOTE: Not available on currently deployed PostgREST
|
|
# db.rollback():
|
|
# $ref: '@supabase/postgrest-js.PostgrestTransformBuilder.rollback'
|
|
# title: rollback()
|
|
# examples:
|
|
# - id: With `delete()`
|
|
# description: |
|
|
# <details>
|
|
# <summary>Schema</summary>
|
|
|
|
# ```sql
|
|
# create table
|
|
# countries (id int8 primary key, name text);
|
|
|
|
# insert into
|
|
# countries (id, name)
|
|
# values
|
|
# (1, 'Spain');
|
|
# ```
|
|
# </details>
|
|
|
|
# ```ts
|
|
# const { error } = await supabase
|
|
# .from('countries')
|
|
# .delete()
|
|
# .eq('id', 1)
|
|
# .rollback()
|
|
# ```
|
|
|
|
# <details>
|
|
# <summary>Result</summary>
|
|
|
|
# ```json
|
|
# {
|
|
# "status": 204,
|
|
# "statusText": "No Content"
|
|
# }
|
|
# ```
|
|
# </details>
|
|
|
|
# ```ts
|
|
# const { data, error } = await supabase
|
|
# .from('countries')
|
|
# .select()
|
|
# ```
|
|
|
|
# <details>
|
|
# <summary>Result</summary>
|
|
|
|
# ```json
|
|
# {
|
|
# "data": [
|
|
# {
|
|
# "id": 1,
|
|
# "name": "Spain"
|
|
# }
|
|
# ],
|
|
# "status": 200,
|
|
# "statusText": "OK"
|
|
# }
|
|
# ```
|
|
# </details>
|
|
# hideCodeBlock: true
|
|
# isSpotlight: true
|
|
# js: |
|
|
# ```ts
|
|
# const { error } = await supabase
|
|
# .from('countries')
|
|
# .delete()
|
|
# .eq('id', 1)
|
|
# ```
|
|
|
|
- id: invoke()
|
|
title: 'invoke()'
|
|
description: |
|
|
Invoke a Supabase Function.
|
|
$ref: '@supabase/functions-js.FunctionsClient.invoke'
|
|
notes: |
|
|
- Requires an Authorization header.
|
|
- Invoke params generally match the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) spec.
|
|
- When you pass in a body to your function, we automatically attach the Content-Type header for `Blob`, `ArrayBuffer`, `File`, `FormData` and `String`. If it doesn't match any of these types we assume the payload is `json`, serialise it and attach the `Content-Type` header as `application/json`. You can override this behaviour by passing in a `Content-Type` header of your own.
|
|
- Responses are automatically parsed as `json`, `blob` and `form-data` depending on the `Content-Type` header sent by your function. Responses are parsed as `text` by default.
|
|
examples:
|
|
- id: basic-invocation.
|
|
name: Basic invocation.
|
|
description:
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.functions.invoke('hello', {
|
|
body: { foo: 'bar' }
|
|
})
|
|
```
|
|
- id: error-handling.
|
|
name: Error handling.
|
|
description: |
|
|
A `FunctionsHttpError` error is returned if your function throws an error, `FunctionsRelayError` if the Supabase Relay has an error processing your function and `FunctionsFetchError` if there is a network error in calling your function.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
import { FunctionsHttpError, FunctionsRelayError, FunctionsFetchError } from "@supabase/supabase-js";
|
|
|
|
const { data, error } = await supabase.functions.invoke('hello', {
|
|
headers: {
|
|
"my-custom-header": 'my-custom-header-value'
|
|
},
|
|
body: { foo: 'bar' }
|
|
})
|
|
|
|
if (error instanceof FunctionsHttpError) {
|
|
const errorMessage = await error.context.json()
|
|
console.log('Function returned an error', errorMessage)
|
|
} else if (error instanceof FunctionsRelayError) {
|
|
console.log('Relay error:', error.message)
|
|
} else if (error instanceof FunctionsFetchError) {
|
|
console.log('Fetch error:', error.message)
|
|
}
|
|
```
|
|
- id: passing-custom-headers.
|
|
name: Passing custom headers.
|
|
description: |
|
|
You can pass custom headers to your function. Note: supabase-js automatically passes the `Authorization` header with the signed in user's JWT.
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase.functions.invoke('hello', {
|
|
headers: {
|
|
"my-custom-header": 'my-custom-header-value'
|
|
},
|
|
body: { foo: 'bar' }
|
|
})
|
|
```
|
|
|
|
- id: subscribe()
|
|
title: 'on().subscribe()'
|
|
$ref: '@supabase/realtime-js.RealtimeChannel.on'
|
|
notes: |
|
|
- Realtime is disabled by default for new Projects for better database performance and security. You can turn it on by [managing replication](/docs/guides/database/api#managing-realtime).
|
|
- Row level security is not applied to delete statements.
|
|
- If you want to receive the "previous" data for updates and deletes, you will need to set `REPLICA IDENTITY` to `FULL`, like this: `ALTER TABLE your_table REPLICA IDENTITY FULL;`
|
|
- When a delete occurs, the contents of old_record will be broadcast to all subscribers to that table so ensure that each table's replica identity only contains information that is safe to expose publicly.
|
|
- The channel name must exactly match the schema/table/filter you want to listen to separated by colons. See below examples for additional context.
|
|
examples:
|
|
- id: listen-to-all-database-changes
|
|
name: Listen to all database changes
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('*')
|
|
.on('postgres_changes', { event: '*', schema: '*' }, payload => {
|
|
console.log('Change received!', payload)
|
|
})
|
|
.subscribe()
|
|
```
|
|
- id: listen-to-a-specific-table
|
|
name: Listen to a specific table
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('public:countries')
|
|
.on('postgres_changes', { event: '*', schema: 'public', table: 'countries' }, payload => {
|
|
console.log('Change received!', payload)
|
|
})
|
|
.subscribe()
|
|
```
|
|
- id: listen-to-inserts
|
|
name: Listen to inserts
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('public:countries')
|
|
.on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, payload => {
|
|
console.log('Change received!', payload)
|
|
})
|
|
.subscribe()
|
|
```
|
|
- id: listen-to-updates
|
|
name: Listen 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 to:
|
|
|
|
```sql
|
|
alter table "your_table" replica identity full;
|
|
```
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('public:countries')
|
|
.on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries' }, payload => {
|
|
console.log('Change received!', payload)
|
|
})
|
|
.subscribe()
|
|
```
|
|
- id: listen-to-deletes
|
|
name: Listen 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:
|
|
|
|
```sql
|
|
alter table "your_table" replica identity full;
|
|
```
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('public:countries')
|
|
.on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, payload => {
|
|
console.log('Change received!', payload)
|
|
})
|
|
.subscribe()
|
|
```
|
|
- id: listen-to-multiple-events
|
|
name: Listen to multiple events
|
|
description: You can chain listeners if you want to listen to multiple events for each table.
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('public:countries')
|
|
.on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, handleRecordInserted)
|
|
.on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, handleRecordDeleted)
|
|
.subscribe()
|
|
```
|
|
- id: listening-to-row-level-changes
|
|
name: Listen to row level changes
|
|
description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match.
|
|
notes: |
|
|
- ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them.
|
|
js: |
|
|
```js
|
|
supabase
|
|
.channel('public:countries:id=eq.200')
|
|
.on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries', filter: 'id=eq.200' }, handleRecordUpdated)
|
|
.subscribe()
|
|
```
|
|
|
|
- id: getChannels()
|
|
title: 'getChannels()'
|
|
$ref: '@supabase/supabase-js.index.SupabaseClient.getChannels'
|
|
examples:
|
|
- id: get-all-channels
|
|
name: Get all channels
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const channels = supabase.getChannels()
|
|
```
|
|
|
|
- id: removeChannel()
|
|
title: 'removeChannel()'
|
|
$ref: '@supabase/supabase-js.index.SupabaseClient.removeChannel'
|
|
notes: |
|
|
- Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
|
|
examples:
|
|
- id: removes-a-channel
|
|
name: Removes a channel
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
supabase.removeChannel(myChannel)
|
|
```
|
|
|
|
- id: removeAllChannels()
|
|
title: 'removeAllChannels()'
|
|
$ref: '@supabase/supabase-js.index.SupabaseClient.removeAllChannels'
|
|
notes: |
|
|
- Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
|
|
examples:
|
|
- id: remove-all-channels
|
|
name: Remove all channels
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
supabase.removeAllChannels()
|
|
```
|
|
|
|
- id: storage.listBuckets()
|
|
title: 'listBuckets()'
|
|
$ref: '@supabase/storage-js.packages/StorageBucketApi.default.listBuckets'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: `select`
|
|
- `objects` table permissions: none
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: list-buckets
|
|
name: List buckets
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.listBuckets()
|
|
```
|
|
|
|
- id: storage.getBucket()
|
|
title: 'getBucket()'
|
|
$ref: '@supabase/storage-js.packages/StorageBucketApi.default.getBucket'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: `select`
|
|
- `objects` table permissions: none
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: get-bucket
|
|
name: Get bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.getBucket('avatars')
|
|
```
|
|
|
|
- id: storage.createBucket()
|
|
title: 'createBucket()'
|
|
$ref: '@supabase/storage-js.packages/StorageBucketApi.default.createBucket'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: `insert`
|
|
- `objects` table permissions: none
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: create-bucket
|
|
name: Create bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.createBucket('avatars', { public: false })
|
|
```
|
|
|
|
- id: storage.emptyBucket()
|
|
title: 'emptyBucket()'
|
|
$ref: '@supabase/storage-js.packages/StorageBucketApi.default.emptyBucket'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: `select`
|
|
- `objects` table permissions: `select` and `delete`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: empty-bucket
|
|
name: Empty bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.emptyBucket('avatars')
|
|
```
|
|
- id: storage.updateBucket()
|
|
title: 'updateBucket()'
|
|
$ref: '@supabase/storage-js.packages/StorageBucketApi.default.updateBucket'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: `update`
|
|
- `objects` table permissions: none
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: update-bucket
|
|
name: Update bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.updateBucket('avatars', { public: false })
|
|
```
|
|
|
|
- id: storage.deleteBucket()
|
|
title: 'deleteBucket()'
|
|
$ref: '@supabase/storage-js.packages/StorageBucketApi.default.deleteBucket'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: `select` and `delete`
|
|
- `objects` table permissions: none
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: delete-bucket
|
|
name: Delete bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.deleteBucket('avatars')
|
|
```
|
|
|
|
- id: storage.from.upload()
|
|
title: 'from.upload()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.upload'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `insert`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
- 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: upload-file
|
|
name: Upload file
|
|
isSpotlight: true
|
|
js: |
|
|
```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: upload-file-using`arraybuffer`from-base64-file-data
|
|
name: Upload file using `ArrayBuffer` from base64 file data
|
|
js: |
|
|
```js
|
|
import { decode } from 'base64-arraybuffer'
|
|
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.upload('public/avatar1.png', decode('base64FileData'), {
|
|
contentType: 'image/png'
|
|
})
|
|
```
|
|
|
|
- id: storage.from.update()
|
|
title: 'from.update()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.update'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `update` and `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
- 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: update-file
|
|
name: Update file
|
|
isSpotlight: true
|
|
js: |
|
|
```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: update-file-using`arraybuffer`from-base64-file-data
|
|
name: Update file using `ArrayBuffer` from base64 file data
|
|
js: |
|
|
```js
|
|
import {decode} from 'base64-arraybuffer'
|
|
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.update('public/avatar1.png', decode('base64FileData'), {
|
|
contentType: 'image/png'
|
|
})
|
|
```
|
|
|
|
- id: storage.from.move()
|
|
title: 'from.move()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.move'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `update` and `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: move-file
|
|
name: Move file
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.move('public/avatar1.png', 'private/avatar2.png')
|
|
```
|
|
|
|
- id: storage.from.copy()
|
|
title: 'from.copy()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.copy'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `insert` and `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: copy-file
|
|
name: Copy file
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.copy('public/avatar1.png', 'private/avatar2.png')
|
|
```
|
|
|
|
- id: storage.from.createSignedUrl()
|
|
title: 'from.createSignedUrl()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUrl'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: create-signed-url
|
|
name: Create Signed URL
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.createSignedUrl('folder/avatar1.png', 60)
|
|
```
|
|
|
|
- id: storage.from.createSignedUrls()
|
|
title: 'from.createSignedUrls()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.createSignedUrls'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: create-signed-urls
|
|
name: Create Signed URLs
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60)
|
|
```
|
|
|
|
- id: storage.from.getPublicUrl()
|
|
title: 'from.getPublicUrl()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.getPublicUrl'
|
|
notes: |
|
|
- The bucket needs to be set to public, either via [updateBucket()](/docs/reference/javascript/storage-updatebucket) or by going to Storage on [supabase.com/dashboard](https://supabase.com/dashboard), clicking the overflow menu on a bucket and choosing "Make public"
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: none
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: returns-the-url-for-an-asset-in-a-public-bucket
|
|
name: Returns the URL for an asset in a public bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data } = supabase
|
|
.storage
|
|
.from('public-bucket')
|
|
.getPublicUrl('folder/avatar1.png')
|
|
```
|
|
|
|
- id: storage.from.download()
|
|
title: 'from.download()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.download'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: download-file
|
|
name: Download file
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.download('folder/avatar1.png')
|
|
```
|
|
|
|
- id: storage.from.remove()
|
|
title: 'from.remove()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.remove'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `delete` and `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: delete-file
|
|
name: Delete file
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.remove(['folder/avatar1.png'])
|
|
```
|
|
|
|
- id: storage.from.list()
|
|
title: 'from.list()'
|
|
$ref: '@supabase/storage-js.packages/StorageFileApi.default.list'
|
|
notes: |
|
|
- RLS policy permissions required:
|
|
- `buckets` table permissions: none
|
|
- `objects` table permissions: `select`
|
|
- Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
|
|
examples:
|
|
- id: list-files-in-a-bucket
|
|
name: List files in a bucket
|
|
isSpotlight: true
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.list('folder', {
|
|
limit: 100,
|
|
offset: 0,
|
|
sortBy: { column: 'name', order: 'asc' },
|
|
})
|
|
```
|
|
- id: search-files-in-a-bucket
|
|
name: Search files in a bucket
|
|
js: |
|
|
```js
|
|
const { data, error } = await supabase
|
|
.storage
|
|
.from('avatars')
|
|
.list('folder', {
|
|
limit: 100,
|
|
offset: 0,
|
|
sortBy: { column: 'name', order: 'asc' },
|
|
search: 'jon'
|
|
})
|
|
```
|