Files
supabase/web/docs/library/get.mdx
T

1008 lines
19 KiB
Plaintext

---
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,
getJsonData,
getOrderJs,
getEmbeddedOrderJs,
getLimitJs,
getEmbeddedLimitJs,
getOffsetJs,
getEmbeddedOffsetJs,
getRangeJs,
getSingleJs,
getFilterJs,
getFilterJsEmbedded,
getNotJs,
getOrJs,
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": "Los Angeles", "country_id": 840 },
{ "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": "Los Angeles" },
{ "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": "Los Angeles " },
{ "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"
}`}
/>
### Quering JSON data
If you have data inside of a JSONB column, you can apply select and query filters to the data values.
Postgres offers a [number of operators](https://www.postgresql.org/docs/9.5/functions-json.html) for querying JSON data.
Also see [PostgREST](http://postgrest.org/en/v7.0.0/api.html#json-columns) docs for more details.
<CustomCodeBlock
header="Shows how to reference a foreign table when it is referenced twice"
js={getJsonData}
jsHighlight="{9-12}"
/>
## Reference
### `from()`
<FromFunction verb="get" />
### `select()`
<!-- prettier-ignore -->
#### General Form
```js {3}
supabase.from(tableName).select(columnQuery)
```
If `'*'` is passd in for `columnQuery`(i.e. `.select('*')`) then 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="{10}"
response={`{
"body": [
{ "name": "San Francisco", "country_id": 840 },
{ "name": "Los Angeles", "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 />
<CustomCodeBlock
header="Shows how to use order( ) with select( ) and foreign tables present"
js={getEmbeddedOrderJs}
jsHighlight="{11}"
response={`{
"body": [
{
"name": "United States",
"cities": [
{ "name": "San Francisco" },
{ "name": "Los Angeles " }
]
},
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<!-- prettier-ignore -->
#### General Form
```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.
---
### `limit()`
<CustomCodeBlock
header="Shows how to use limit( ) with select( )"
js={getLimitJs}
jsHighlight="{10}"
response={`{
"body": [
{ "name": "Rio de Janeiro", "country_id": 76 }
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<CustomCodeBlock
header="Shows how to use limit( ) and foreign tables present"
js={getEmbeddedLimitJs}
jsHighlight="{11}"
response={`{
"body": [
{
"name": "United States",
"cities": [
{ "name": "Los Angeles " }
]
},
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<!-- prettier-ignore -->
#### General Form
```js {3}
supabase.from(tableName).limit(criteria, foreignTableName)
```
Orders your data before fetching.
#### `criteria: number`
Specifies number of items to be returned at most.
#### `foreignTableName: string ? | Default is null`
Name of chosen foreignTable to apply the limit on. Used if foreign tables are present.
---
### `offset()`
<CustomCodeBlock
header="Shows how to use offset( ) with select( )"
js={getOffsetJs}
jsHighlight="{10}"
response={`{
"body": [
{ "name": "Beijing", "country_id": 156 },
{ "name": "Paris", "country_id": 250 },
{ "name": "Auckland", "country_id": 554 },
{ "name": "Lagos", "country_id": 556 },
{ "name": "Los Angeles", "country_id": 840 },
{ "name": "San Francisco", "country_id": 840 }
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<CustomCodeBlock
header="Shows how to use offset( ) with select( ) and foreign tables present"
js={getEmbeddedOffsetJs}
jsHighlight="{11}"
response={`{
"body": [
{
"name": "United States",
"cities": [
{ "name": "San Francisco" }
]
},
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<!-- prettier-ignore -->
#### General Form
```js {3}
supabase.from(tableName).offset(criteria, foreignTableName)
```
Orders your data before fetching.
#### `criteria: number`
Specifies number of items to be returned at most.
#### `foreignTableName: string ? | Default is null`
Name of chosen foreignTable to apply the limit on. Used if foreign tables are present.
---
### `range()`
<CustomCodeBlock
header="Shows how to use range( ) with select( )"
js={getRangeJs}
jsHighlight="{10}"
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 -->
#### General Form
```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 -->
#### General Form
```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="{10}"
response={`{
"body": [
{ "name": "Paris", "country_id": 250 },
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<CustomCodeBlock
header="Shows how to use filter embedded tables"
js={getFilterJsEmbedded}
jsHighlight="{10}"
response={`{
"body": [
{
"name": "Paris",
"country": { "name": "France" }
},
],
"status": 200,
"statusCode": 200,
"statusText": "OK"
}`}
/>
<br />
<CommonFilters filter="filter" />
### `not()`
<CustomCodeBlock
header="Shows how to use not( ) with select( )"
js={getNotJs}
jsHighlight="{10}"
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" />
### `or()`
<CustomCodeBlock
header="Shows how to use or( ) with select( )"
js={getOrJs}
jsHighlight="{10}"
/>
<br />
<CommonFilters filter="or" />
### `match()`
<CustomCodeBlock
header="Shows how to use match( ) with select( )"
js={getMatchJs}
jsHighlight="{10}"
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="{10}"
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="{10}"
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": "Los Angeles", "country_id": 840 },
{ "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="{10}"
response={`{
"body": [
{ "name": "Auckland", "country_id": 554 },
{ "name": "Lagos", "country_id": 556 },
{ "name": "Los Angeles", "country_id": 840 },
{ "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="{10}"
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="{10}"
response={`{
"body": [
{ "name": "Paris", "country_id": 250 },
{ "name": "Auckland", "country_id": 554 },
{ "name": "Lagos", "country_id": 556 },
{ "name": "Los Angeles", "country_id": 840 },
{ "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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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="{10}"
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 />