Modifier

Modifiers are used to alter the format of a response. Unlike filters, they act on operations above the row-level.

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

select

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

⚠️ Note: The .select() method will return the inserted rows only when there is only one primary key in the table and it is of auto-increment data type.

Parameter

Parameter Name	Data Type	Required	Description
columns	string	no	Columns to retrieve, separated by commas

Sample Code

Execute an upsert operation in the articles table and return the complete record after modification
const { data, error } = await db
  .from("articles")
.insert({ id: 1, title: "Tencent Cloud develops new features" })
  .select();

order

Sort the query result.

You can call this method multiple times to sort by multiple columns.

You can sort the referenced table, but it only impacts the parent table's sorting when !inner is used in the query.

Parameter

Parameter Name	Data Type	Required	Description
column	string	yes	Column to sort
options	object	No	Named parameters

Parameter details of options

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

Sample Code

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

Sort the reference table

Sort the reference 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 reference 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 returned rows.

Parameter

Parameter Name	Data Type	Required	Description
count	number	Yes	The maximum number of rows to return
options	object	No	Named parameters

Parameter details for options

Parameter Name	Data Type	Required	Description
referencedTable	string	No	Set to limit the number of table rows for the referenced table rather than the parent table

Sample Code

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

Limit the number of table rows for the 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 query result range.

Limit the query result by starting from offset from to to, only records within this range will be returned.

This follows the query sequence. If there is no sorting clause, the range action may be unpredictable.

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

Parameter

Parameter Name	Data Type	Required	Description
from	number	yes	start index of result restriction
to	number	yes	end index of result restriction
options	object	Yes	Named parameters

Parameter details for options

Parameter Name	Data Type	Required	Description
referencedTable	string	No	Set to limit the number of table rows for the referenced table rather than the parent table

Sample Code

Retrieve the first 2 records of the article list (including boundary values).
const { data, error } = await db.from("articles").select("title").range(0, 1);

Limit the access scope of the reference table

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

abortSignal

💡 Note: This method is only available in the Web environment.

Set AbortSignal for the fetch request.

You can use this feature to set a timeout for the request.

Parameter

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

Sample Code

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

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

single

Retrieving a single row of data.

Return the data as a single object rather than an object array.

The query result must have only one row (such as using .limit(1)), otherwise this method will return an error.

Sample Code

// 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.

Return the data as a single object rather than an object array.

The query result must have zero or one row (such as using .limit(1)), otherwise this method will return an error.

Sample Code

// Search for articles by title, may not exist
const { data, error } = await db
  .from("articles")
  .select()
.eq("title", "Tencent Cloud develops new features")
  .maybeSingle();

overrideTypes

Partially overwrite or replacement successful response type.

Override the return type of the data field in response, super useful for type-safe query result switch.

Parameter

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

Parameter details for options

Parameter Name	Data Type	Required	Description
merge	boolean	No	If false, replace the type completely rather than merge

Sample Code

Entirely overwrite array type

// Overwrite the response data entirely with a custom array type, merge: false means complete overwrite instead of merge
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<MyType>, { merge: false }>();

Entirely overwrite object type

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

Partially overwrite array type

// Partially overwrite array element types, specify only the field types that need to be altered (for example, the status field)
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<{ status: "A" | "B" }>>();

Partially overwrite object type

// Partially overwrite single object types, specify only the field types that need to be altered (for example, the status field)
const { data } = await db
  .from("articles")
  .select()
  .maybeSingle()
  .overrideTypes<{ status: "A" | "B" }>();