Reading
Toggle Example Tables
We will be fictional "world" database in all of our examples.
id | name | iso2 | population_range_millions | main_exports |
---|---|---|---|---|
76 | Brazil | BR | ( 205, 215 ) | [ beans, minerals ] |
156 | China | CN | ( 1380, 1390 ) | [ computers, phones ] |
250 | France | FR | ( 60, 70 ) | [ cars, machines ] |
554 | New Zealand | NZ | ( 4, 6 ) | [ food, machines ] |
556 | Nigeria | NG | ( 185, 195 ) | [ oil, beans ] |
840 | United States | US | ( 320, 330 ) | [ oil, cars, food ] |
name | country_id |
---|---|
Rio de Janeiro | 76 |
Beijing | 156 |
Paris | 250 |
Auckland | 554 |
Lagos | 556 |
Los Angeles | 840 |
San Francisco | 840 |
Getting your data
Getting specific columns
Query foreign tables
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:
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 for querying JSON data. Also see PostgREST docs for more details.
Reference
from()
tableName: string
Name of the database table that will be read from.
select()
General Form
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}')
Show detailed example
order()
General Form
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()
General Form
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()
General Form
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()
General Form
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()
General Form
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()
General form
This allows you to apply various filters on your query. Filters can also be chained together.
columnName: string
Name of the database column.
operator: string
Name of filter operator to be utilised.
criteria: { object | array | string | integer | boolean | null }
Value to compare to. Exact data type of criteria would depend on the operator used.
not()
General form
Reverse of .filter()
. Returns rows that do not meet the criteria specified using the columnName and operator provided.
columnName: string
Name of the database column.
operator: string
Name of filter operator to be utilised.
criteria: { object | array | string | integer | boolean | null }
Value to compare to. Exact data type of criteria would depend on the operator used.
or()
General form
To write append an OR
filter, which should be made up of several other filters.
criteria: { string }
Filters to apply.
match()
General form
Finds rows that exactly match the specified filterObject. Equivalent of multiple filter('columnName', 'eq', criteria)
.
filterObject: object
An object of { 'columnName': 'criteria' }
eq()
General form
Finds all rows whose value on the stated columnName exactly matches the specified filterValue. Equivalent of filter(columnName, 'eq', criteria)
.
columnName: string
Name of the database column.
filterValue: { string | integer | boolean }
Value to match.
neq()
General form
Finds all rows whose value on the stated columnName does not match the specified filterValue. Equivalent of filter(columnName, 'neq', criteria)
.
columnName: string
Name of database column.
filterValue: { string | integer | boolean }
Value to not match.
gt()
General form
Finds all rows whose value on the stated columnName is greater than the specified filterValue. Eqiuvalent of filter(columnName, 'gt', criteria)
.
columnName: string
Name of database column.
filterValue: { string | integer | boolean }
Value to compare to.
lt()
General form
Finds all rows whose value on the stated columnName is less than the specified filterValue. Eqiuvalent of filter(columnName, 'lt', criteria)
.
columnName: string
Name of database column.
filterValue: { string | integer | boolean }
Value to compare to.
gte()
General form
Finds all rows whose value on the stated columnName is greater than or equal to the specified filterValue. Eqiuvalent of filter(columnName, 'gte', criteria)
.
columnName: string
Name of database column.
filterValue: { string | integer | boolean }
Value to compare to.
lte()
General form
Finds all rows whose value on the stated columnName is less than or equal to the specified filterValue. Eqiuvalent of filter(columnName, 'lte', criteria)
.
columnName: string
Name of database column.
filterValue: { string | integer | boolean }
Value to compare to.
like()
General form
Finds all rows whose value in the stated columnName matches the supplied pattern. Equivalent of filter(columnName, 'like', stringPattern)
.
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.
ilike()
General form
A case-sensitive version of like()
. Equivalent of filter(columnName, 'ilike', stringPattern)
.
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.
is()
General form
A check for exact equality (null, true, false), finds all rows whose value on the state columnName exactly match the specified filterValue.
Equivalent of filter(columnName, 'is', filterValue)
.
columnName: string
Name of database column.
filterValue: { null | boolean }
Value to match.
in()
General form
Finds all rows whose value on the stated columnName is found on the specified filterArray. Equivalent of filter(columnName, 'in', criteria)
.
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.
cs()
General form
Finds all rows whose json, array, or range value on the stated columnName contains the items specified in the filterObject. Equivalent of filter(columName, 'cs', criteria)
.
columnName: string
Name of the database column.
filterObject: { array | object }
Value to compare to.
cd()
General form
Finds all rows whose json, array, or range value on the stated columnName is contained by the specific filterObject. Equivalent of filter(columName, 'cd', criteria)
.
columnName: string
Name of the database column.
filterObject: { array | object }
Value to compare to.
ova()
General form
Finds all rows whose array value on the stated columnName overlaps with the specified filterArray. Equivalent of filter(columnName, 'ova', criteria)
.
columnName: string
Name of the database column.
filterArray: array
Value to compare to.
ovr()
General form
Finds all rows whose range value on the stated columnName overlaps with the specified filterRange. Equivalent of filter(columnName, 'ovr', criteria)
.
columnName: string
Name of the database column.
filterRange: array
Array to compare to. Returns an error if length of array provided is not equal to 2.
sl()
General form
Finds all rows whose range value on the stated columnName is strictly on the left hand side of the specified filterRange. Equivalent of filter(columnName, 'sl', criteria)
.
columnName: string
Name of the database column.
filterRange: array
Array to compare to. Returns an error if length of array provided is not equal to 2.
sr()
General form
Finds all rows whose range value on the stated columnName is strictly on the right hand side of the specified filterRange. Equivalent of filter(columnName, 'sr', criteria)
.
columnName: string
Name of the database column.
filterRange: array
Array to compare to. Returns an error if length of array provided is not equal to 2.
nxl()
General form
Finds all rows whose range value on the stated columnName does not extend to the left of the specified filterRange. Equivalent of filter(columnName, 'nxl', criteria)
.
columnName: string
Name of the database column.
filterRange: array
Array to compare to. Returns an error if length of array provided is not equal to 2.
nxr()
General form
Finds all rows whose range value on the stated columnName does not extend to the right of the specified filterRange. Equivalent of filter(columnName, 'nxr', criteria)
.
columnName: string
Name of the database column.
filterRange: array
Array to compare to. Returns an error if length of array provided is not equal to 2.
adj()
General form
Finds all rows whose range value on the stated columnName is adjacent to the specified filterRange. Equivalent of filter(columnName, 'adj', criteria)
.
columnName: string
Name of the database column.
filterRange: array
Array to compare to. Returns an error if length of array provided is not equal to 2.
Responses
200 OK
Successful request
400 Bad request
An invalid syntax or configuration was sent.
401 Unauthorized
Invalid credentials were provided.
404 Not found
Requested resource cannot be found.
406 Not acceptable
The response provided by the server does not match the list of acceptable values stated in the request's headers.
409 Violating foreign key constraint
Raised when you are trying to insert or update into a table with a foreign key which doesn't exist on the target foreign relationship.
500 Internal Server Error
The server was unable to encounter the situation it encountered.