Stored Procedures

You can call stored procedures as a "Remote Procedure Call".

That's a fancy way of saying that you can put some logic into your database then call it from anywhere. This is especially useful when the logic rarely changes - like password resets and updates.

Here, we have three stored procedures that will act as our examples:

echo_city : Takes in objects containing a city name and returns that name.

echo_all_cities : Returns all rows in the table Cities.

echo_all_countries : Returns all rows in the table Countries.

Toggle Example Tables

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

Countries

id	name	iso2	population_range_millions	main_exports
76	Brazil	BR	( 205, 215 )	[ beans, minerals ]
156	China	CN	( 1380, 1390 )	[ computers, phones ]
250	France	FR	( 60, 70 )	[ cars, machines ]
554	New Zealand	NZ	( 4, 6 )	[ food, machines ]
556	Nigeria	NG	( 185, 195 )	[ oil, beans ]
840	United States	US	( 320, 330 )	[ oil, cars, food ]

Cities

name	country_id
Rio de Janeiro	76
Beijing	156
Paris	250
Auckland	554
Lagos	556
Los Angeles	840
San Francisco	840

Single call

Example of invoking a stored procedure that taking in a name of a city and returning it.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCity = async () => {

try{

let city = await supabase

.rpc('echo_city', { name: 'The Shire' })

return cities

} catch (error) {

console.log('Error: ', error)

}

}

}

Show Response

Bulk call

This example would call a the same stored procedure above (twice), but it will also wait to receive the response only when all the calls have completed:

Example of invoking the same stored procedure multiple times within one call.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try{

let cities = await supabase

.rpc('echo_city', [

{ name: 'The Shire' },

{ name: 'Mordor' }

])

return cities

} catch (error) {

console.log('Error: ', error)

}

}

}

Show Response

Reading data

This example shows how to call a stored function that returns a table type response:

Example of invoking the same stored procedure multiple times within one call.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try{

let cities = await supabase

.rpc('echo_all_cities')

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

Reference

rpc()

supabase.rpc(functionName, functionParameters)

functionName: string

Name of stored function in the database.

functionParameters: { object? | array? }

Parameters to be passed to the stored function.

---

Filtering

filter()

Shows how to use filter( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.filter({'name', 'eq', 'Paris'})

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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.

---

not()

Shows how to use not( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities)

.not('name', 'eq', 'Paris')

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.not(columnName, operator, criteria)

Reverse of .filter(). Returns rows that do not meet the criteria specified using the columnName and operator provided.

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.match({name: 'Beijing', country_id: 156})

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.eq('name', 'San Francisco')

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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(columnName, 'eq', criteria).

columnName: string

Name of the database column.

filterValue: { string | integer | boolean }

Value to match.

---

neq()

Shows how to use neq( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.neq('name', 'Lagos')

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.neq(columnName, filterValue)

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

columnName: string

Name of database column.

filterValue: { string | integer | boolean }

Value to not match.

---

gt()

Shows how to use gt( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.gt('country_id', 250)

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.lt('country_id', 250)

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.gte('country_id', 250)

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.lte('country_id', 250)

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.like('name', '%la%')

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.ilike('name', '%la%')

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.is('name', null)

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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 rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCities = async () => {

try {

let cities = await supabase

.rpc('echo_all_cities')

.in('name', ['Rio de Janeiro', 'San Francisco'])

return cities

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

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.

---

cs()

Shows how to use cs( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.cs('main_exports', ['oil'])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.cs(columnName, filterObject)

Finds all rows whose json, array, or range value on the stated columnName contains the items specified in the filterObject. Equivalent of filter(columName, 'cs', criteria).

columnName: string

Name of the database column.

filterObject: { array | object }

Value to compare to.

---

cd()

Shows how to use cd( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.cd('main_exports', ['cars', 'food', 'machine'])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.cd(columnName, filterObject)

Finds all rows whose json, array, or range value on the stated columnName is contained by the specific filterObject. Equivalent of filter(columName, 'cd', criteria).

columnName: string

Name of the database column.

filterObject: { array | object }

Value to compare to.

---

ova()

Shows how to use ova( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.ova('main_exports', ['computers', 'minerals'])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.ova(columnName, filterArray)

Finds all rows whose array value on the stated columnName overlaps with the specified filterArray. Equivalent of filter(columnName, 'ova', criteria).

columnName: string

Name of the database column.

filterArray: array

Value to compare to.

---

ovr()

Shows how to use ovr( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.ovr('population_range_millions', [150, 250])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.ovr(columnName, filterRange)

Finds all rows whose range value on the stated columnName overlaps with the specified filterRange. Equivalent of filter(columnName, 'ovr', criteria).

columnName: string

Name of the database column.

filterRange: array

Array to compare to. Returns an error if length of array provided is not equal to 2.

---

sl()

Shows how to use sl( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.sl('population_range_millions', [150, 250])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.sl(columnName, filterRange)

Finds all rows whose range value on the stated columnName is strictly on the left hand side of the specified filterRange. Equivalent of filter(columnName, 'sl', criteria).

columnName: string

Name of the database column.

filterRange: array

Array to compare to. Returns an error if length of array provided is not equal to 2.

---

sr()

Shows how to use sr( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.sr('population_range_millions', [150, 250])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.sr(columnName, filterRange)

Finds all rows whose range value on the stated columnName is strictly on the right hand side of the specified filterRange. Equivalent of filter(columnName, 'sr', criteria).

columnName: string

Name of the database column.

filterRange: array

Array to compare to. Returns an error if length of array provided is not equal to 2.

---

nxl()

Shows how to use nxl( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.nxl('population_range_millions', [150, 250])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.nxl(columnName, filterRange)

Finds all rows whose range value on the stated columnName does not extend to the left of the specified filterRange. Equivalent of filter(columnName, 'nxl', criteria).

columnName: string

Name of the database column.

filterRange: array

Array to compare to. Returns an error if length of array provided is not equal to 2.

---

nxr()

Shows how to use nxr( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.nxr('population_range_millions', [150, 250])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.nxr(columnName, filterRange)

Finds all rows whose range value on the stated columnName does not extend to the right of the specified filterRange. Equivalent of filter(columnName, 'nxr', criteria).

columnName: string

Name of the database column.

filterRange: array

Array to compare to. Returns an error if length of array provided is not equal to 2.

---

adj()

Shows how to use adj( ) with rpc( )

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.co', 'public-key-bOYapLADERfE')

const echoCountries = async () => {

try {

let countries = await supabase

.rpc('echo_all_countries')

.adj('population_range_millions', [70, 185])

return countries

} catch (error) {

console.log('Error: ', error)

}

}

Show Response

General form

supabase

.from(tableName)

.adj(columnName, filterRange)

Finds all rows whose range value on the stated columnName is adjacent to the specified filterRange. Equivalent of filter(columnName, 'adj', criteria).

columnName: string

Name of the database column.

filterRange: array

Array to compare to. Returns an error if length of array provided is not equal to 2.

---

Responses

200 OK

Successful request

201 Created

Successful

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.

409 Violating foreign key constraint

Raised when you are trying to insert or update into a table with a foreign key which doesn't exist on the target foreign relationship.

500 Internal Server Error

The server was unable to encounter the situation it encountered.