Skip to main content
Version: v2 RC

Fetch data: select()

Perform a SELECT query on the table or view.

const { data, error } = await supabase
.from('countries')
.select()

Parameters

  • columnsoptionalQuery

    The columns to retrieve, separated by commas

  • optionsrequiredobject

    Named parameters

      Properties
    • countoptionalexact | planned | estimated

      Count algorithm to use to count rows in the table or view.

      "exact": Exact but slow count algorithm. Performs a COUNT(*) under the hood.

      "planned": Approximated but fast count algorithm. Uses the Postgres statistics under the hood.

      "estimated": Uses exact count for low numbers and planned count for high numbers.

    • headoptionalboolean

      When set to true, data will not be returned. Useful if you only need the count.

Notes

  • By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's API settings. It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use range() queries to paginate through your data.
  • select() can be combined with Filters
  • select() can be combined with Modifiers
  • apikey is a reserved keyword if you're using the Supabase Platform and should be avoided as a column name](https://github.com/supabase/supabase/issues/5465).

Examples

Getting your data

const { data, error } = await supabase
.from('countries')
.select()

Selecting specific columns

You can select specific fields from your tables.

const { data, error } = await supabase
.from('countries')
.select('name')

Query foreign tables

If your database has foreign key relationships, you can query related tables too.

const { data, error } = await supabase
.from('countries')
.select(`
name,
cities (
name
)
`)

Query foreign tables through a join table

If you're in a situation where your tables are NOT directly related, but instead are joined by a join table, you can still use the select() method to query the related data. The join table needs to have the foreign keys as part of its composite primary key.

const { data, error } = await supabase
.from('users')
.select(`
name,
teams (
name
)
`)

Query the same foreign table multiple times

If you need to query the same foreign table twice, use the name of the joined column to identify which join to use. You can also give each column an alias.

const { data, error } = await supabase
.from('messages')
.select(`
content,
from:sender_id(name),
to:receiver_id(name)
`)

Filtering through foreign tables

If the filter on a foreign table's column is not satisfied, the foreign table returns [] or null but the parent table is not filtered out.

const { data, error } = await supabase
.from('cities')
.select('name, countries(*)')
.eq('countries.name', 'Estonia')

If you want to filter out the parent table rows, use the !inner hint:

const { data, error } = await supabase
.from('cities')
.select('name, countries!inner(*)')
.eq('countries.name', 'Estonia')

Querying with count option

You can get the number of rows by using the count option. For example, to get the table count without returning all rows:

const { count, error } = await supabase
.from('countries')
.select('*', { count: 'exact', head: true })

Querying JSON data

You can select and filter data inside of JSON columns. Postgres offers some operators for querying JSON data.

const { data, error } = await supabase
.from('users')
.select(`
id, name,
address->city
`)