Modifiers

Modifiers are used to change the format of the response, unlike filters, which operate above the row level.

Filters only return rows that match specific conditions without changing the shape of the rows, while modifiers allow changing the format of the response.

select

By default, .insert() does not return the inserted rows. By calling this method, the inserted rows will be returned in the data.

Warning: The .select() method returns the inserted rows only when the table has a single primary key and that primary key is of auto-increment type.

Parameters

Parameter	Type	Required	Description
columns	string	No	Columns to retrieve, separated by commas

Code Example

// Perform an insert operation in the articles table and return the modified full record
const { data, error } = await db
  .from("articles")
  .insert({ id: 1, title: "Tencent CloudBase New Feature" })
  .select();

order

Sort the query results.

This method can be called multiple times to sort by multiple columns.

The referenced table can be sorted, but it will affect the sorting of the parent table only when !inner is used in the query.

Parameters

Parameter	Type	Required	Description
column	string	Yes	Column to sort
options	object	No	Named parameters

options Parameter Details

Parameter	Type	Required	Description
ascending	boolean	No	If true, the results will be sorted in ascending order
nullsFirst	boolean	No	If true, null values will appear first. If false, null values will appear last
referencedTable	string	No	Set to sort by the columns of the referenced table

Code Example

// Sort articles by publication time in descending order
const { data, error } = await db
  .from("articles")
  .select("id, title, published_at")
  .order("published_at", { ascending: false });

Sort Referenced Table

// Sort the referenced table categories by name in descending order
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    categories (
      name
    )
  `)
  .order("name", { referencedTable: "categories", ascending: false });

// Sort by the name column of the referenced table category in ascending order
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    category:categories (
      name
    )
  `)
  .order("category(name)", { ascending: true });

limit

Limit the number of rows returned.

Parameters

Parameter	Type	Required	Description
count	number	Yes	Maximum number of rows to return
options	object	No	Named parameters

options Parameter Details

Parameter	Type	Required	Description
referencedTable	string	No	Set to limit rows of the referenced table instead of the parent table

Code Example

// Limit to returning 5 articles
const { data, error } = await db.from("articles").select("title").limit(5);

Limit Rows of Referenced Table

// Only return 3 categories per article
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    categories (
      name
    )
  `)
  .limit(3, { referencedTable: "categories" });

range

Limit the range of query results.

Limits query results by starting from offset from to to. Only records within this range will be returned.

This follows the query order. If there is no order clause, the range behavior may be unpredictable.

The from and to values are 0-based and inclusive: range(1, 3) will include the second, third, and fourth rows of the query.

Parameters

Parameter	Type	Required	Description
from	number	Yes	Starting index of the range
to	number	Yes	Ending index of the range
options	object	Yes	Named parameters

options Parameter Details

Parameter	Type	Required	Description
referencedTable	string	No	Set to limit rows of the referenced table instead of the parent table

Code Example

// Get records 1-2 from the article list (inclusive)
const { data, error } = await db.from("articles").select("title").range(0, 1);

Range on Referenced Table

// Only return the first 2 categories per article (index 0-1)
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    categories (
      name
    )
  `)
  .range(0, 1, { referencedTable: "categories" });

abortSignal

Note: This method is only available in Web environments.

Set an AbortSignal for the fetch request.

This feature can be used to set a timeout for requests.

Parameters

Parameter	Type	Required	Description
signal	AbortSignal	Yes	AbortSignal for the fetch request

Code Example

// Manually abort a request using AbortController
const ac = new AbortController();
ac.abort();
const { data, error } = await db
  .from("articles")
  .select()
  .abortSignal(ac.signal);

// Set a 1-second timeout using AbortSignal.timeout
const { data, error } = await db
  .from("articles")
  .select()
  .abortSignal(AbortSignal.timeout(1000));

single

Retrieve a single row of data.

Returns data as a single object instead of an array of objects.

The query result must contain only one row (e.g., by using .limit(1)), otherwise this method will return an error.

Code Example

// Get the title of the first article
const { data, error } = await db
  .from("articles")
  .select("title")
  .limit(1)
  .single();

maybeSingle

Retrieve zero or one row of data.

Returns data as a single object instead of an array of objects.

The query result must contain zero or one row (e.g., by using .limit(1)), otherwise this method will return an error.

Code Example

// Find an article by title, which may not exist
const { data, error } = await db
  .from("articles")
  .select()
  .eq("title", "Tencent CloudBase New Feature")
  .maybeSingle();

overrideTypes

Partially override or replace the type of a successful response.

Overrides the return type of the data field in the response, useful for type-safe query result transformations.

Parameters

Parameter	Type	Required	Description
type	T	Yes	Type to override
options	object	No	Options object

options Parameter Details

Parameter	Type	Required	Description
merge	boolean	No	If false, completely replaces the type instead of merging

Code Examples

Fully Override Array Type

// Fully override the response data to a custom array type, merge: false means full replacement instead of merging
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<MyType>, { merge: false }>();

Fully Override Object Type

// Used with maybeSingle to fully override a single object response to a custom type
const { data } = await db
  .from("articles")
  .select()
  .maybeSingle()
  .overrideTypes<MyType, { merge: false }>();

Partially Override Array Type

// Partially override array element types, specifying only the field types that need to change (e.g., status field)
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<{ status: "A" | "B" }>>();

Partially Override Object Type

// Partially override a single object type, specifying only the field types that need to change (e.g., status field)
const { data } = await db
  .from("articles")
  .select()
  .maybeSingle()
  .overrideTypes<{ status: "A" | "B" }>();