PostgrestTransformBuilder
import { PostgrestTransformBuilder } from "https://esm.sh/@supabase/supabase-js@2.108.1/dist/index.d.mts";§Type Parameters
§Methods
Set the AbortSignal for the fetch request.
- The AbortSignal to use for the fetch request
Aborting requests in-flight
const ac = new AbortController()
const { data, error } = await supabase
.from('very_big_table')
.select()
.abortSignal(ac.signal)
// Abort the request after 100 ms
setTimeout(() => ac.abort(), 100)
Set a timeout
const { data, error } = await supabase
.from('very_big_table')
.select()
.abortSignal(AbortSignal.timeout(1000 /* ms *\/))
Return data as a string in CSV format.
Return data as CSV
const { data, error } = await supabase
.from('characters')
.select()
.csv()
Return data as the EXPLAIN plan for the query.
You need to enable the db_plan_enabled setting before using this method.
- Named parameters
- If
true, the query will be executed and the actual run time will be returned
- If
true, the query identifier will be returned anddatawill include the output columns of the query
- If
true, include information on configuration parameters that affect query planning
- If
true, include information on buffer usage
- If
true, include information on WAL record generation
- The format of the output, can be
"text"(default) or"json"
Get the execution plan
const { data, error } = await supabase
.from('characters')
.select()
.explain()
Get the execution plan with analyze and verbose
const { data, error } = await supabase
.from('characters')
.select()
.explain({analyze:true,verbose:true})
Return data as an object in GeoJSON format.
Limit the query result by rows.
- The maximum number of rows to return
- Named parameters
- Set this to limit rows of referenced tables instead of the parent table
- Deprecated, use
options.referencedTableinstead
With select()
const { data, error } = await supabase
.from('characters')
.select('name')
.limit(1)
On a referenced table
const { data, error } = await supabase
.from('orchestral_sections')
.select(`
name,
instruments (
name
)
`)
.limit(1, { referencedTable: 'instruments' })
Set the maximum number of rows that can be affected by the query. Only available in PostgREST v13+ and only works with PATCH and DELETE methods.
- The maximum number of rows that can be affected
Return data as a single object instead of an array of objects.
Query result must be zero or one row (e.g. using .limit(1)), otherwise
this returns an error.
With select()
const { data, error } = await supabase
.from('characters')
.select()
.eq('name', 'Katniss')
.maybeSingle()
Use options.referencedTable instead of options.foreignTable
Use options.referencedTable instead of options.foreignTable
Limit the query result by starting at an offset from and ending at the offset to.
Only records within this range are returned.
This respects the query order and if there is no order clause the range could behave unexpectedly.
The from and to values are 0-based and inclusive: range(1, 3) will include the second, third
and fourth rows of the query.
- The starting index from which to limit the result
- The last index to which to limit the result
- Named parameters
- Set this to limit rows of referenced tables instead of the parent table
- Deprecated, use
options.referencedTableinstead
With select()
const { data, error } = await supabase
.from('characters')
.select('name')
.range(0, 1)
Override the type of the returned data.
Use overrideTypes<yourType, { merge: false }>() method at the end of your call chain instead
Override type of successful response
const { data } = await supabase
.from('countries')
.select()
.returns<Array<MyType>>()
Override type of object response
const { data } = await supabase
.from('countries')
.select()
.maybeSingle()
.returns<MyType>()
Dry-run this request: execute the query but discard the changes.
Server-side, PostgREST runs the query inside a transaction and rolls it back
instead of committing. The response still contains the data that would have
been returned — RETURNING clauses execute and RLS, triggers, and constraints
are all evaluated — but no row is actually inserted, updated, or deleted.
This affects only the single request it is chained to. The JS caller has no
handle on the transaction: supabase-js does not group multiple queries into
one transaction. For multi-statement transactional logic, use a database
function (supabase.rpc(...)).
Sets the Prefer: tx=rollback header. See PostgREST's docs on transaction
preferences for the underlying mechanism.
Validate an insert without persisting
const { data, error } = await supabase
.from('countries')
.insert({ name: 'France' })
.select()
.rollback()
// `data` shows what would have been inserted; nothing is saved.
Perform a SELECT on the query result.
By default, .insert(), .update(), .upsert(), and .delete() do not
return modified rows. By calling this method, modified rows are returned in
data.
- The columns to retrieve, separated by commas
With upsert()
const { data, error } = await supabase
.from('characters')
.upsert({ id: 1, name: 'Han Solo' })
.select()
Return data as a single object instead of an array of objects.
Query result must be one row (e.g. using .limit(1)), otherwise this
returns an error.
With select()
const { data, error } = await supabase
.from('characters')
.select('name')
.limit(1)
.single()