modifier

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, the inserted rows are not returned by .insert(). By invoking this method, the inserted rows will be returned in the data.

⚠️ Note: 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 Name	Type	Required	Description
columns	string	No	columns to search, separated by commas

Code Example

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

order

Sorting 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 Name	Type	Required	Description
column	string	Yes	Column to sort
options	object	No	Named parameters

options Parameter Details

Parameter Name	Type	Required	Description
ascending	boolean	No	If true, the results will be sorted in ascending order
nullsFirst	boolean	No	If true, null values will be placed first. If false, null values will be placed 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 });

Sorting Referenced Tables

// 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 Name	Type	Required	Description
count	number	Yes	Maximum number of rows to return
options	object	No	Named parameters

options Parameter Details

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

Code Example

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

Limiting the Number of Rows in Referenced Tables

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

range

Limit the scope of query results.

By restricting the query results from offset from to to, only records within this range will be returned.

This follows the query order; without an ORDER BY clause, the range behavior may be unpredictable.

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

Parameters

Parameter Name	Type	Required	Description
from	number	Yes	Limit the starting index of the results
to	number	Yes	Limit the ending index of the results
options	object	Yes	Named parameters

options Parameter Details

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

Code Example

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

Applying Range Restrictions to Referenced Tables

// Return only 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 a Web environment.

Set the AbortSignal for the fetch request.

You can use this feature to set a timeout for requests.

Parameters

Parameter Name	Type	Required	Description
signal	AbortSignal	Required	AbortSignal for fetch requests

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);

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

single

Searching for a single row of data.

Return the data as a single object instead of an array of objects.

The query result must contain exactly one row (e.g., using .limit(1)); otherwise, this method will throw an error.

Code Example

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

maybeSingle

Searching for zero or one row of data.

Return the data as a single object instead of an array of objects.

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

Code Example

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

overrideTypes

Partial override or replacement of the successful response type.

Override the return type of the data field in the response, which is very useful for type-safe transformation of query results.

Parameters

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

options Parameter Details

Parameter Name	Type	Required	Description
merge	boolean	No	If false, the type is replaced entirely instead of being merged

Code Example

Completely Override Array Type

// Completely override the response data to a custom array type, merge: false indicates completely replace instead of merge
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<MyType>, { merge: false }>();

Completely Override Object Type

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

Partial Override Array Type

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

Partial Override Object Type

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