Reading

Toggle Example Tables

We will be fictional "world" database in all of our examples.

Countries
idnameiso2continent
76BrazilBRSouth America
156ChinaCNAsia
250FranceFREurope
554New ZealandNZOceania
566NigeriaNGAfrica
840United StatesUSNorth America
Cities
namecountry_id
Rio de Janeiro76
Beijing156
Paris250
Auckland554
Lagos556
San Francisco840

Getting your data

Shows how to get all cities from our public 'world' database
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

Getting specific columns

Shows how to get all cities but only return the name
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.select('name')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

Query foreign tables

Shows how to get all countries and the name of each of their cities
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCountries = async () => {
try {
let countries = await supabase
.from('countries')
.select(`
name,
cities (
name
)
`)
return countries
} catch (error) {
console.log('Error: ', error)
}
}

Query the same foreign table multiple times

Sometimes you will need to query the same foreign table twice. In this case, you can use the name of the joined column to identify which join you intend to use. For convenience, you can also give an alias for each column. For example, if we had a shop of products, and we wanted to get the supplier and the purchaser at the same time (both in the users) table:

Shows how to reference a foreign table when it is referenced twice
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://shop.supabase.co', 'public-key-bOYapLADERfE')
const getProducts = async () => {
try {
let products = await supabase
.from('products')
.select(`
id,
supplier:supplier_id ( name ),
purchaser:purchaser_id ( name )
`)
return products
} catch (error) {
console.log('Error: ', error)
}
}

Reference

from()

supabase
.from(tableName)

tableName: string

Name of the database table to be listened to. Using the wildcard "*" will lead to all tables to be listened to.

tableName: string

Name of the database table that will be read from.

tableName: string

Name of the database table where data will be saved.

tableName: string

Name of the database table where data will be updated.

tableName: string

Name of the database table where data will be deleted.


select()

supabase
.from(tableName)
.select(columnQuery)

If not used, all columns in the table will be returned.

columnQuery: string

A comma separated list of columns. For example select('id, name')

If a foreign key constraint exists between this table and another, you can also query the columns of the related table. For example select('name, cities {name}')

Show detailed example
supabase
.from('countries')
.select(`
name,
cities {
name,
population
}
`)

order()

Shows how to use order( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.order('id')
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

supabase
.from(tableName)
.order(columnName, sortAscending, nullsFirst)

Orders your data before fetching.

columnName: string

Name of chosen column to base the order on.

sortAscending: boolean? | Default is false

Specifies whether the order will be ascending or descending.

nullsFirst: boolean? | Default is false

Specifies whether null values will be displayed first.


range()

Shows how to use range( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.range(0,3)
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

supabase
.from(tableName)
.range(fromIndex, toIndex)

Paginates your request.

fromIndex: integer

Index or position of the start of the specified range.

toIndex: integer?

Index or position of the end of the specified range. If not stated, all remaining rows after the starting index will be returned.


single()

Shows how to use single( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.range(0)
.single()
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

supabase
.from(tableName)
.single()

Sets the header which signifies to PostgREST that the response must either be a single object with 200 OK. Otherwise, it will return an error with 406 Not Acceptable.


Filtering

filter()

Shows how to use filter( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.filter({'name', 'eq', 'Paris'})
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.filter(columnName, operator, criteria)

This allows you to apply various filters on your query. Filters can also be chained together.

columnName: string

Name of the database column.

operator: string

Name of filter operator to be utilised.

criteria: { object | array | string | integer | boolean | null }

Value to compare to. Exact data type of criteria would depend on the operator used.


match()

Shows how to use match( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.match({name: 'Beijing', country_id: 156})
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.match(filterObject)

Finds rows that exactly match the specified filterObject. Equivalent of multiple filter('columnName', 'eq', criteria).

filterObject: object

An object of { 'columnName': 'criteria' }


eq()

Shows how to use eq( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.eq('name', 'San Francisco')
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.eq(columnName, filterValue)

Finds all rows whose value on the stated columnName exactly matches the specified filterValue. Equivalent of filter(columName, 'eq', criteria).

columnName: string

Name of the database column.

filterValue: { string | integer | boolean }

Value to match.


gt()

Shows how to use gt( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.gt('country_id', 250)
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.gt(columnName, filterValue)

Finds all rows whose value on the stated columnName is greater than the specified filterValue. Eqiuvalent of filter(columnName, 'gt', criteria).

columnName: string

Name of database column.

filterValue: { string | integer | boolean }

Value to compare to.


lt()

Shows how to use lt( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.lt('country_id', 250)
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.lt(columnName, filterValue)

Finds all rows whose value on the stated columnName is less than the specified filterValue. Eqiuvalent of filter(columnName, 'lt', criteria).

columnName: string

Name of database column.

filterValue: { string | integer | boolean }

Value to compare to.


gte()

Shows how to use gte( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.gte('country_id', 250)
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.gte(columnName, filterValue)

Finds all rows whose value on the stated columnName is greater than or equal to the specified filterValue. Eqiuvalent of filter(columnName, 'gte', criteria).

columnName: string

Name of database column.

filterValue: { string | integer | boolean }

Value to compare to.


lte()

Shows how to use lte( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.lte('country_id', 250)
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.lte(columnName, filterValue)

Finds all rows whose value on the stated columnName is less than or equal to the specified filterValue. Eqiuvalent of filter(columnName, 'lte', criteria).

columnName: string

Name of database column.

filterValue: { string | integer | boolean }

Value to compare to.


like()

Shows how to use like( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.like('name', '%la%')
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.like(columnName, stringPattern)

Finds all rows whose value in the stated columnName matches the supplied pattern. Equivalent of filter(columnName, 'like', stringPattern).

columnName: string

Name of database column.

stringPattern: string

String pattern to compare to. A comprehensive guide on how to form proper patterns can be found here.


ilike()

Shows how to use ilike( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.ilike('name', '%la%')
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.ilike(columnName, stringPattern)

A case-sensitive version of like(). Equivalent of filter(columnName, 'ilike', stringPattern).

columnName: string

Name of database column.

stringPattern: string

String pattern to compare to. A comprehensive guide on how to form proper patterns can be found here.


is()

Shows how to use is( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.is('name', null)
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.is(columnName, filterValue)

A check for exact equality (null, true, false), finds all rows whose value on the state columnName exactly match the specified filterValue. Equivalent of filter(columnName, 'is', filterValue).

columnName: string

Name of database column.

filterValue: { null | boolean }

Value to match.


in()

Shows how to use in( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.in('name', ['Rio de Janeiro', 'San Francisco'])
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.in(columnName, filterArray)

Finds all rows whose value on the stated columnName is found on the specified filterArray. Equivalent of filter(columnName, 'in', criteria).

columnName: string

Name of database column.

filterArray: array

Array of values to find a match. Data type of values is dependent on the columnName specified.


not()

Shows how to use not( ) with select( )
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')
const getCities = async () => {
try {
let cities = await supabase
.from('cities')
.not('name', 'Lagos')
.select('*')
return cities
} catch (error) {
console.log('Error: ', error)
}
}

General form

supabase
.from(tableName)
.not(columnName, filterValue)

Finds all rows whose value on the stated columnName does not match the specified filterValue. Equivalent of filter(columnName, 'not', criteria).

columnName: string

Name of database column.

filterValue: { string | integer | boolean }

Value to not match.


Responses

200 OK

Successful request

400 Bad request

An invalid syntax or configuration was sent.

401 Unauthorized

Invalid credentials were provided.

404 Not found

Requested resource cannot be found.

406 Not acceptable

The response provided by the server does not match the list of acceptable values stated in the request's headers.

500 Internal Server Error

The server was unable to encounter the situation it encountered.