supabase/web/docs/library/get.mdx

---
id: get
title: 'Reading'
description: 'How to fetch records from your database with Supabase'
---

import CommonFilters from '../common/CommonFilters'
import CommonResponses from '../common/CommonResponses.mdx'
import Collapsable from '../../src/components/Collapsable'
import FromFunction from '../common/FromFunction.mdx'
import DummyData from '../common/DummyData.mdx'
import CustomCodeBlock from '../../src/components/CustomCodeBlock'
import {
  getSimpleJs,
  getColumnsJs,
  getForeignJs,
  getForeignMultipleJs,
  getOrderJs,
  getRangeJs,
  getSingleJs,
  getFilterJs,
  getNotJs,
  getMatchJs,
  getEqJs,
  getNeqJs,
  getGtJs,
  getLtJs,
  getGteJs,
  getLteJs,
  getLikeJs,
  getIlikeJs,
  getIsJs,
  getInJs,
  getCsJs,
  getCdJs,
  getOvaJs,
  getOvrJs,
  getSlJs,
  getSrJs,
  getNxlJs,
  getNxrJs,
  getAdjJs,
} from './examples/get'

<DummyData />

### Getting your data

<CustomCodeBlock
  header="Shows how to get all cities from our public 'world' database"
  js={getSimpleJs}
  jsHighlight="{7-9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "Beijing", "country_id": 156 },
    { "name": "Paris", "country_id": 250 },
    { "name": "Auckland", "country_id": 554 },
    { "name": "Lagos", "country_id": 556 },
    { "name": "San Francisco", "country_id": 840 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

### Getting specific columns

<CustomCodeBlock
  header="Shows how to get all cities but only return the name"
  js={getColumnsJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro" },
    { "name": "Beijing" },
    { "name": "Paris" },
    { "name": "Auckland" },
    { "name": "Lagos" },
    { "name": "San Francisco" }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

### Query foreign tables

<CustomCodeBlock
  header="Shows how to get all countries and the name of each of their cities"
  js={getForeignJs}
  jsHighlight="{9-14}"
  response={`{
  "body": [
    {
      "name": "Brazil",  
      "cities": [
        { "name": "Rio de Janeiro" }
      ]
    },
    {
      "name": "China", 
      "cities": [
        { "name": "Beijing" }
      ]
    },
    {
      "name": "France", 
      "cities": [
        { "name": "Paris" }
      ]
    },
    {
      "name": "New Zealand", 
      "cities": [
        { "name": "Auckland" }
      ]
    },
    {
      "name": "Nigeria", 
      "cities": [
        { "name": "Lagos" }
      ]
    },
    {
      "name": "United States", 
      "cities": [
        { "name": "San Francisco" }
      ]
    }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

### Query the same foreign table multiple times

Sometimes you will need to query the same foreign table twice. In this case, you can use the name of the joined column to identify which join you intend to use.
For convenience, you can also give an alias for each column. For example, if we had a shop of products, and we wanted to get
the supplier and the purchaser at the same time (both in the `users`) table:

<CustomCodeBlock
  header="Shows how to reference a foreign table when it is referenced twice"
  js={getForeignMultipleJs}
  jsHighlight="{9-13}"
  response={`{
  "body": [
    {
      "id": 1,  
      "purchaser": { "name": "John" },  
      "supplier":  { "name": "Jane" }
    },
    {
      "id": 2,  
      "purchaser": { "name": "Sue" },  
      "supplier":  { "name": "Steve" }
    }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

## Reference

### `from()`

<FromFunction verb="get" />

### `select()`

<!-- prettier-ignore -->
```js {3}
supabase
  .from(tableName)
  .select(columnQuery)
```

If not used, all columns in the table will be returned.

#### `columnQuery: string`

A comma separated list of columns. For example `select('id, name')`

If a foreign key constraint exists between this table
and another, you can also query the columns of the related table. For example `select('name, cities {name}')`

<Collapsable title="Show detailed example">

<!-- prettier-ignore -->
```js
supabase
  .from('countries')
  .select(`
    name,
    cities {
      name,
      population
    }
  `)
```

</Collapsable>

---

### `order()`

<CustomCodeBlock
  header="Shows how to use order( ) with select( )"
  js={getOrderJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "San Francisco", "country_id": 840 },
    { "name": "Lagos", "country_id": 556 },
    { "name": "Auckland", "country_id": 554 },
    { "name": "Paris", "country_id": 250 },
    { "name": "Beijing", "country_id": 156 },
    { "name": "Rio de Janeiro", "country_id": 76 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<!-- prettier-ignore -->
```js {3}
supabase
  .from(tableName)
  .order(columnName, sortAscending, nullsFirst)
```

Orders your data before fetching.

#### `columnName: string`

Name of chosen column to base the order on.

#### `sortAscending: boolean? | Default is false`

Specifies whether the order will be ascending or descending.

#### `nullsFirst: boolean? | Default is false`

Specifies whether null values will be displayed first.

---

### `range()`

<CustomCodeBlock
  header="Shows how to use range( ) with select( )"
  js={getRangeJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "Beijing", "country_id": 156 },
    { "name": "Paris", "country_id": 250 },
    { "name": "Auckland", "country_id": 554 },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<!-- prettier-ignore -->
```js {3}
supabase
  .from(tableName)
  .range(fromIndex, toIndex)
```

Paginates your request.

#### `fromIndex: integer`

Index or position of the start of the specified range.

#### `toIndex: integer?`

Index or position of the end of the specified range. If not stated, all remaining rows after the starting index will be returned.

---

### `single()`

<CustomCodeBlock
  header="Shows how to use single( ) with select( )"
  js={getSingleJs}
  jsHighlight="{10}"
  response={`{
  "body": { 
    "name": "San Francisco", "country_id": 840 
  },
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<!-- prettier-ignore -->
```js {3}
supabase
  .from(tableName)
  .single()
```

Sets the header which signifies to PostgREST that the response must either be a single object
with `200 OK`. Otherwise, it will return an error with `406 Not Acceptable`.

---

## Filtering

### `filter()`

<CustomCodeBlock
  header="Shows how to use filter( ) with select( )"
  js={getFilterJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Paris", "country_id": 250 },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="filter" />

### `not()`

<CustomCodeBlock
  header="Shows how to use not( ) with select( )"
  js={getNotJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "Beijing", "country_id": 156 },
    { "name": "Auckland", "country_id": 554 },
    { "name": "Lagos", "country_id": 556 },
    { "name": "San Francisco", "country_id": 840 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="not" />

### `match()`

<CustomCodeBlock
  header="Shows how to use match( ) with select( )"
  js={getMatchJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Beijing", "country_id": 156 },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="match" />

### `eq()`

<CustomCodeBlock
  header="Shows how to use eq( ) with select( )"
  js={getEqJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "San Francisco", "country_id": 840 },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="eq" />

### `neq()`

<CustomCodeBlock
  header="Shows how to use neq( ) with select( )"
  js={getNeqJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "Beijing", "country_id": 156 },
    { "name": "Paris", "country_id": 250 },
    { "name": "Auckland", "country_id": 554 },
    { "name": "Lagos", "country_id": 556 },
    { "name": "San Francisco", "country_id": 840 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="neq" />

### `gt()`

<CustomCodeBlock
  header="Shows how to use gt( ) with select( )"
  js={getGtJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Auckland", "country_id": 554 },
    { "name": "Lagos", "country_id": 556 },
    { "name": "San Francisco", "country_id": 840 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="gt" />

### `lt()`

<CustomCodeBlock
  header="Shows how to use lt( ) with select( )"
  js={getLtJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "Beijing", "country_id": 156 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="lt" />

### `gte()`

<CustomCodeBlock
  header="Shows how to use gte( ) with select( )"
  js={getGteJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Paris", "country_id": 250 },
    { "name": "Auckland", "country_id": 554 },
    { "name": "Lagos", "country_id": 556 },
    { "name": "San Francisco", "country_id": 840 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="gte" />

### `lte()`

<CustomCodeBlock
  header="Shows how to use lte( ) with select( )"
  js={getLteJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "Beijing", "country_id": 156 },
    { "name": "Paris", "country_id": 250 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="lte" />

### `like()`

<CustomCodeBlock
  header="Shows how to use like( ) with select( )"
  js={getLikeJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Auckland", "country_id": 554 },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="like" />

### `ilike()`

<CustomCodeBlock
  header="Shows how to use ilike( ) with select( )"
  js={getIlikeJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Auckland", "country_id": 554 },
    { "name": "Lagos", "country_id": 556 },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="ilike" />

### `is()`

<CustomCodeBlock
  header="Shows how to use is( ) with select( )"
  js={getIsJs}
  jsHighlight="{9}"
  response={`{
  "body": [
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="is" />

### `in()`

<CustomCodeBlock
  header="Shows how to use in( ) with select( )"
  js={getInJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Rio de Janeiro", "country_id": 76 },
    { "name": "San Francisco", "country_id": 840 }
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="in" />

### `cs()`

<CustomCodeBlock
  header="Shows how to use cs( ) with select( )"
  js={getCsJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Nigeria", "id": 556, "main_exports": ["oil", "beans"] },
    { "name": "United States", "id": 840, "main_exports": ["oil", "cars", "food"] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="cs" />

### `cd()`

<CustomCodeBlock
  header="Shows how to use cd( ) with select( )"
  js={getCdJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "France", "id": 250, "main_exports": ["cars", "machines"] },
    { "name": "New Zealand", "id": 554, "main_exports": ["food", "machines"] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="cd" />

### `ova()`

<CustomCodeBlock
  header="Shows how to use ova( ) with select( )"
  js={getOvaJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Brazil", "id": 76, "main_exports": ["beans", "minerals"] },
    { "name": "China", "id": 156, "main_exports": ["computers", "phones"] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="ova" />

### `ovr()`

<CustomCodeBlock
  header="Shows how to use ovr( ) with select( )"
  js={getOvrJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Brazil", "id": 76, "population_range_millions": [205, 215] },
    { "name": "Nigeria", "id": 556, "population_range_millions": [185, 195] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="ovr" />

### `sl()`

<CustomCodeBlock
  header="Shows how to use sl( ) with select( )"
  js={getSlJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "France", "id": 250, "population_range_millions": [60, 70] },
    { "name": "New Zealand", "id": 554, "population_range_millions": [4, 6] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="sl" />

### `sr()`

<CustomCodeBlock
  header="Shows how to use sr( ) with select( )"
  js={getSrJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "China", "id": 156, "population_range_millions": [1380, 1390] },
    { "name": "United States", "id": 840, "population_range_millions": [320, 330] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="sr" />

### `nxl()`

<CustomCodeBlock
  header="Shows how to use nxl( ) with select( )"
  js={getNxlJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Brazil", "id": 76, "population_range_millions": [205, 215] },
    { "name": "China", "id": 156, "population_range_millions": [1380, 1390] },
    { "name": "Nigeria", "id": 556, "population_range_millions": [185, 195] },
    { "name": "United States", "id": 840, "population_range_millions": [320, 330] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="nxl" />

### `nxr()`

<CustomCodeBlock
  header="Shows how to use nxr( ) with select( )"
  js={getNxrJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "Brazil", "id": 76, "population_range_millions": [205, 215] },
    { "name": "France", "id": 250, "population_range_millions": [60, 70] },
    { "name": "New Zealand", "id": 554, "population_range_millions": [4, 6] },
    { "name": "Nigeria", "id": 556, "population_range_millions": [185, 195] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="nxr" />

### `adj()`

<CustomCodeBlock
  header="Shows how to use adj( ) with select( )"
  js={getAdjJs}
  jsHighlight="{9}"
  response={`{
  "body": [
    { "name": "France", "id": 250, "population_range_millions": [60, 70] },
    { "name": "Nigeria", "id": 556, "population_range_millions": [185, 195] },
  ],
  "status": 200,
  "statusCode": 200,
  "statusText": "OK"
}`}
/>

<br />

<CommonFilters filter="adj" />

## Responses

#### 200 OK

Successful request

<CommonResponses />