supabase/web/docs/library/get.mdx

---
id: get
title: 'Reading your data'
---

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import DummyData from '../common/DummyData.mdx'
import CommonResponses from '../common/CommonResponses.mdx'
import Collapsable from '../../src/components/Collapsable'

We will be using these tables as reference for our examples:

<DummyData />

### Getting your data

This example shows how to get all the countries in our database.

<!-- prettier-ignore -->
```js {7-8}
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

const getCities = async () => {
  try {
    let cities = await supabase
      .get('cities')
    return cities
  } catch (error) {
    console.log('Error: ', error)
  }
}
```

<details>
<summary>Show response</summary>
<div>

Calling `getCities()` will return the following response:

```json
[
  { "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 }
]
```

</div>
</details>

### Getting specific columns

Get all cities but only return the name.

<!-- prettier-ignore -->
```js {9}
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

const getCities = async () => {
  try {
    let cities = await supabase
      .get('cities')
      .select('name')
    return cities
  } catch (error) {
    console.log('Error: ', error)
  }
}
```

<details>
<summary><b>Show response</b></summary>
<div>
  
Calling `getCities()` will return the following response:

```json
[
  { "name": "Rio de Janeiro" },
  { "name": "Beijing" },
  { "name": "Paris" },
  { "name": "Auckland" },
  { "name": "Lagos" },
  { "name": "San Francisco" }
]
```

</div>
</details>

### Query foreign tables

Get all users and return all information about them and the companies they belong to.

<!-- prettier-ignore -->
```js {9-15}
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

const getCountries = async () => {
  try {
    let countries = await supabase
      .get('countries')
      .select(`
        name,
        cities {
          name
        }
      `)
    return countries
  } catch (error) {
    console.log('Error: ', error)
  }
}
```


<details>
<summary><b>Show response</b></summary>
<div>

Calling `getCountries()` will return the following response:

```json
[
  {
    "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" }
    ]
  }
]
```

</div>
</details>

## Reference


### `get()`

<!-- prettier-ignore -->
```js {2}
supabase
  .get(tableName)
```

##### tableName `:string`
Name of table in the database that will be read from.


----

### `select()`

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

##### columnName `:string`
Select only the specified columns. For example `select('id, name')`. Similar to a GraphQL, if a foreign key constraint exists between this table 
and another, information from the other table can be requested as well. For example:

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


----

### `order()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(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()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(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()`

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

Returns the first row of the table as an object and **not** as an array.

----

### `match()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .match(filterObject)
```

Returns an array of rows that exactly match the specified filterObject.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .match({ 'continent': 'Asia'})
```

</Collapsable>


##### filterObject `:object`
An object of `{ 'columnName': 'criteria' }`

----

### `eq()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .eq(columnName, filterValue)
```

"Equals": Returns an array of rows whose value on the stated columnName exactly matches the specified filterValue.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .eq('name', 'New Zealand')
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterValue `{:string|:integer|:boolean}`
Value to match.

----

### `gt()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .gt(columnName, filterValue)
```

"Greater Than": Returns an array of rows whose value on the stated columnName exactly matches the specified filterValue.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .gt('id', 20)
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterValue `{:string|:integer|:boolean}`
Value to compare to.

----


### `lt()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .lt(columnName, filterValue)
```

"Less Than": Returns an array of rows whose value on the stated columnName is less than the specified filterValue.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .lt('id', 20)
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterValue `{:string|:integer|:boolean}`
Value to compare to.

----

### `gte()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .gte(columnName, filterValue)
```

"Greater Than or Equal": Returns an array of rows whose value on the stated columName is greater than or equal to the specified filterValue.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .gte('id', 20)
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterValue `{:string|:integer|:boolean}`
Value to compare to.

----

### `lte()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .lte(columnName, filterValue)
```

"Less Than or Equal": Returns an array of rows whose value on the stated columnName is less than or equal to the specified filterValue.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .gte('id', 20)
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterValue `{:string|:integer|:boolean}`
Value to compare to.

----

### `like()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .like(columnName, stringPattern)
```

Returns an array of rows whose value in the stated columnName matches the supplied pattern.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .like('name', '%United%')
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### stringPattern `:string`
String pattern to compare to. A comprehensive guide on how to form proper patterns can be found [here](https://www.postgresql.org/docs/current/functions-matching.html).


----

### `ilike()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .ilike(columnName, stringPattern)
```

A case-insensitive version of `like()`.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .ilike('name', '%united%')
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### stringPattern `:string`
String pattern to compare to. A comprehensive guide on how to form proper patterns can be found [here](https://www.postgresql.org/docs/current/functions-matching.html).


----


### `is()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .is(columnName, stringPattern)
```

A check for exact equality (**null**, **true**, **false**), returns an array of rows whose value on the stated columnName exactly match the specified filterValue.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .is('name', null)
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### stringPattern `{:null|:boolean}`
Value to match.

----

### `in()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .is(columnName, filterArray)
```

Returns an array of rows whose value on the stated columnName is found on the specified filterArray.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .in('name', ['China', 'France'])
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterArray `:array`
Array of values to find a match. Data type of values is dependent on the columnName specified.


----

### `not()`

<!-- prettier-ignore -->
```js {3}
supabase
  .get(tableName)
  .not(columnName, filterValue)
```

Returns an array of rows whose value on the stated columnName is found on the specified filterArray.

<Collapsable title="Toggle Example">

<!-- prettier-ignore -->
```js
supabase
  .get('countries')
  .not('name', 'China')
```

</Collapsable>

##### columnName `:string`
Name of database column.

##### filterValue `{:string|:integer|:boolean}`
Value to **not** match.

----




## Responses

#### 200 OK
Successful request

<CommonResponses />