Tables and Views

All views and tables of the exposed schema and accessible by the active database role are available for querying. They are exposed in one-level deep routes.


For instance the full contents of a table people is returned at

GET /people HTTP/1.1

There are no deeply/nested/routes. Each route provides OPTIONS, GET, HEAD, POST, PATCH, and DELETE verbs depending entirely on database permissions.


Why not provide nested routes? Many APIs allow nesting to retrieve related information, such as /films/1/director. We offer a more flexible mechanism (inspired by GraphQL) to embed related information. It can handle one-to-many and many-to-many relationships. This is covered in the section about Resource Embedding.

Horizontal Filtering

You can filter result rows by adding conditions on columns. For instance, to return people aged under 13 years old:

GET /people?age=lt.13 HTTP/1.1

You can evaluate multiple conditions on columns by adding more query string parameters. For instance, to return people who are 18 or older and are students:

GET /people?age=gte.18&student=is.true HTTP/1.1


These operators are available:


In PostgreSQL







greater than



greater than or equal



less than



less than or equal


<> or !=

not equal



LIKE operator (to avoid URL encoding you can use * as an alias of the percent sign % for the pattern)



ILIKE operator (to avoid URL encoding you can use * as an alias of the percent sign % for the pattern)



~ operator, see Pattern Matching



~* operator, see Pattern Matching



one of a list of values, e.g. ?a=in.(1,2,3) – also supports commas in quoted strings like ?a=in.("hi,there","yes,you")



checking for exact equality (null,true,false,unknown)



not equal, treating NULL as a comparable value



Full-Text Search using to_tsquery



Full-Text Search using plainto_tsquery



Full-Text Search using phraseto_tsquery



Full-Text Search using websearch_to_tsquery



contains e.g. ?tags=cs.{example, new}



contained in e.g. ?values=cd.{1,2,3}



overlap (have points in common), e.g. ?period=ov.[2017-01-01,2017-06-30] – also supports array types, use curly braces instead of square brackets e.g. :code: ?arr=ov.{1,3}



strictly left of, e.g. ?range=sl.(1,10)



strictly right of



does not extend to the right of, e.g. ?range=nxr.(1,10)



does not extend to the left of



is adjacent to, e.g. ?range=adj.(1,10)



negates another operator, see Logical operators



logical OR, see Logical operators



logical AND, see Logical operators



comparison matches all the values in the list, see Logical operators



comparison matches any value in the list, see Logical operators

For more complicated filters you will have to create a new view in the database, or use a stored procedure. For instance, here’s a view to show “today’s stories” including possibly older pinned stories:

CREATE VIEW fresh_stories AS
  FROM stories
 WHERE pinned = true
    OR published > now() - interval '1 day'
ORDER BY pinned DESC, published DESC;

The view will provide a new endpoint:

GET /fresh_stories HTTP/1.1

Logical operators

Multiple conditions on columns are evaluated using AND by default, but you can combine them using OR with the or operator. For example, to return people under 18 or over 21:

GET /people?or=(, HTTP/1.1

To negate any operator, you can prefix it with not like ?a=not.eq.2 or ?not.and=(a.gte.0,a.lte.100) .

You can also apply complex logic to the conditions:

GET /people?grade=gte.90&student=is.true&or=(age.eq.14,not.and(age.gte.11,age.lte.17)) HTTP/1.1

Operator Modifiers

You may further simplify the logic using the any/all modifiers of eq,like,ilike,gt,gte,lt,lte,match,imatch.

For instance, to avoid repeating the same column for or, use any to get people with last names that start with O or P:

GET /people?last_name=like(any).{O*,P*} HTTP/1.1

In a similar way, you can use all to avoid repeating the same column for and. To get the people with last names that start with O and end with n:

GET /people?last_name=like(all).{O*,*n} HTTP/1.1

Pattern Matching

The pattern-matching operators (like, ilike, match, imatch) exist to support filtering data using patterns instead of concrete strings, as described in the PostgreSQL docs.

To ensure best performance on larger data sets, an appropriate index should be used and even then, it depends on the pattern value and actual data statistics whether an existing index will be used by the query planner or not.

Vertical Filtering

When certain columns are wide (such as those holding binary data), it is more efficient for the server to withhold them in a response. The client can specify which columns are required using the select parameter.

GET /people?select=first_name,age HTTP/1.1
  {"first_name": "John", "age": 30},
  {"first_name": "Jane", "age": 20}

The default is *, meaning all columns. This value will become more important below in Resource Embedding.

Renaming Columns

You can rename the columns by prefixing them with an alias followed by the colon : operator.

GET /people?select=fullName:full_name,birthDate:birth_date HTTP/1.1
  {"fullName": "John Doe", "birthDate": "04/25/1988"},
  {"fullName": "Jane Doe", "birthDate": "01/12/1998"}

Casting Columns

Casting the columns is possible by suffixing them with the double colon :: plus the desired type.

GET /people?select=full_name,salary::text HTTP/1.1
  {"full_name": "John Doe", "salary": "90000.00"},
  {"full_name": "Jane Doe", "salary": "120000.00"}

JSON Columns

You can specify a path for a json or jsonb column using the arrow operators(-> or ->>) as per the PostgreSQL docs.

  id int,
  json_data json
GET /people?select=id,json_data->>blood_type,json_data->phones HTTP/1.1
  { "id": 1, "blood_type": "A-", "phones": [{"country_code": "61", "number": "917-929-5745"}] },
  { "id": 2, "blood_type": "O+", "phones": [{"country_code": "43", "number": "512-446-4988"}, {"country_code": "43", "number": "213-891-5979"}] }
GET /people?select=id,json_data->phones->0->>number HTTP/1.1
  { "id": 1, "number": "917-929-5745"},
  { "id": 2, "number": "512-446-4988"}

This also works with filters:

GET /people?select=id,json_data->blood_type&json_data->>blood_type=eq.A- HTTP/1.1
  { "id": 1, "blood_type": "A-" },
  { "id": 3, "blood_type": "A-" },
  { "id": 7, "blood_type": "A-" }

Note that ->> is used to compare blood_type as text. To compare with an integer value use ->:

GET /people?select=id,json_data->age&json_data->age=gt.20 HTTP/1.1
  { "id": 11, "age": 25 },
  { "id": 12, "age": 30 },
  { "id": 15, "age": 35 }

Composite / Array Columns

The arrow operators(->, ->>) can also be used for accessing composite fields and array elements.

CREATE TYPE coordinates (
  lat decimal(8,6),
  long decimal(9,6)

CREATE TABLE countries (
  id int,
  location coordinates,
  languages text[]
GET /countries?select=id,location->>lat,location->>long,primary_language:languages->0&location->lat=gte.19 HTTP/1.1
    "id": 5,
    "lat": "19.741755",
    "long": "-155.844437",
    "primary_language": "en"


When using the -> and ->> operators on composite and array columns, PostgREST uses a query like to_jsonb(<col>)->'field'. To make filtering and ordering on those nested fields use an index, the index needs to be created on the same expression, including the to_jsonb(...) call:

CREATE INDEX ON mytable ((to_jsonb(data) -> 'identification' ->> 'registration_number'));


The reserved word order reorders the response rows. It uses a comma-separated list of columns and directions:

GET /people?order=age.desc,height.asc HTTP/1.1

If no direction is specified it defaults to ascending order:

GET /people?order=age HTTP/1.1

If you care where nulls are sorted, add nullsfirst or nullslast:

GET /people?order=age.nullsfirst HTTP/1.1
GET /people?order=age.desc.nullslast HTTP/1.1

You can also sort on fields of Composite / Array Columns or JSON Columns.

GET /countries?order=location->>lat HTTP/1.1


All tables and auto-updatable views can be modified through the API, subject to permissions of the requester’s database role.

To create a row in a database table post a JSON object whose keys are the names of the columns you would like to create. Missing properties will be set to default values when applicable.

POST /table_name HTTP/1.1

{ "col1": "value1", "col2": "value2" }
HTTP/1.1 201 Created

No response body will be returned by default but you can use Return Representation to get the affected resource.


URL encoded payloads can be posted with Content-Type: application/x-www-form-urlencoded.

POST /people HTTP/1.1
Content-Type: application/x-www-form-urlencoded



When inserting a row you must post a JSON object, not quoted JSON.

{ "a": 1, "b": 2 }

"{ \"a\": 1, \"b\": 2 }"

Some JavaScript libraries will post the data incorrectly if you’re not careful. For best results try one of the Client-Side Libraries built for PostgREST.


It’s recommended that you use triggers instead of rules. Insertion on views with complex rules might not work out of the box with PostgREST due to its usage of CTEs. If you want to keep using rules, a workaround is to wrap the view insertion in a stored procedure and call it through the Stored Procedures interface. For more details, see this github issue.

Bulk Insert

Bulk insert works exactly like single row insert except that you provide either a JSON array of objects having uniform keys, or lines in CSV format. This not only minimizes the HTTP requests required but uses a single INSERT statement on the back-end for efficiency.

To bulk insert CSV simply post to a table route with Content-Type: text/csv and include the names of the columns as the first row. For instance

POST /people HTTP/1.1
Content-Type: text/csv

J Doe,62,70

An empty field (,,) is coerced to an empty string and the reserved word NULL is mapped to the SQL null value. Note that there should be no spaces between the column names and commas.

To bulk insert JSON post an array of objects having all-matching keys

POST /people HTTP/1.1
Content-Type: application/json

  { "name": "J Doe", "age": 62, "height": 70 },
  { "name": "Janus", "age": 10, "height": 55 }

Bulk Insert with Default Values

Any missing columns in the payload will be inserted as null values. To use the DEFAULT column value instead, use the Prefer: missing=default header.


create table foo (
  id bigint generated by default as identity primary key
, bar text
, baz int default 100

A request:

POST /foo?columns=id,bar,baz HTTP/1.1
Content-Type: application/json
Prefer: missing=default, return=representation

  { "bar": "val1"
, { "bar": "val2"
  , "baz": 15

Will result in:

  { "id":  1
  , "bar": "val1"
  , "baz": 100
, { "id":  2
  , "bar": "val2"
  , "baz": 15

Specifying Columns

By using the columns query parameter it’s possible to specify the payload keys that will be inserted and ignore the rest of the payload.

POST /datasets?columns=source,publication_date,figure HTTP/1.1
Content-Type: application/json

  "source": "Natural Disaster Prevention and Control",
  "publication_date": "2015-09-11",
  "figure": 1100,
  "location": "...",
  "comment": "...",
  "extra": "...",
  "stuff": "..."

In this case, only source, publication_date and figure will be inserted. The rest of the JSON keys will be ignored.

Using this also has the side-effect of being more efficient for Bulk Insert since PostgREST will not process the JSON and it’ll send it directly to PostgreSQL.


To update a row or rows in a table, use the PATCH verb. Use Horizontal Filtering to specify which record(s) to update. Here is an example query setting the category column to child for all people below a certain age.

PATCH /people?age=lt.13 HTTP/1.1

{ "category": "child" }

Updates also support Return Representation plus Vertical Filtering.


Beware of accidentally updating every row in a table. To learn to prevent that see Block Full-Table Operations.


You can make an upsert with POST and the Prefer: resolution=merge-duplicates header:

POST /employees HTTP/1.1
Prefer: resolution=merge-duplicates

  { "id": 1, "name": "Old employee 1", "salary": 30000 },
  { "id": 2, "name": "Old employee 2", "salary": 42000 },
  { "id": 3, "name": "New employee 3", "salary": 50000 }

By default, upsert operates based on the primary key columns, you must specify all of them. You can also choose to ignore the duplicates with Prefer: resolution=ignore-duplicates. This works best when the primary key is natural, but it’s also possible to use it if the primary key is surrogate (example: “id serial primary key”). For more details read this issue.


After creating a table or changing its primary key, you must refresh PostgREST schema cache for upsert to work properly. To learn how to refresh the cache see Schema Cache Reloading.

On Conflict

By specifying the on_conflict query parameter, you can make upsert work on a column(s) that has a UNIQUE constraint.

POST /employees?on_conflict=name HTTP/1.1
Prefer: resolution=merge-duplicates

  { "name": "Old employee 1", "salary": 40000 },
  { "name": "Old employee 2", "salary": 52000 },
  { "name": "New employee 3", "salary": 60000 }


A single row upsert can be done by using PUT and filtering the primary key columns with eq:

PUT /employees?id=eq.4 HTTP/1.1

{ "id": 4, "name": "Sara B.", "salary": 60000 }

All the columns must be specified in the request body, including the primary key columns.


To delete rows in a table, use the DELETE verb plus Horizontal Filtering. For instance deleting inactive users:

DELETE /user?active=is.false HTTP/1.1

Deletions also support Return Representation plus Vertical Filtering.

DELETE /user?id=eq.1 HTTP/1.1
Prefer: return=representation
{"id": 1, "email": ""}


Beware of accidentally deleting all rows in a table. To learn to prevent that see Block Full-Table Operations.

Limited Update/Delete

You can limit the amount of affected rows by Update or Delete with the limit query parameter. For this, you must add an explicit order on a unique column(s).

PATCH /users?limit=10&order=id&last_login=lt.2017-01-01 HTTP/1.1

{ "status": "inactive" }
DELETE /users?limit=10&order=id&status=eq.inactive HTTP/1.1

If your table has no unique columns, you can use the ctid system column.

Using offset to target a different subset of rows is also possible.


There is no native UPDATE...LIMIT or DELETE...LIMIT support in PostgreSQL; the generated query simulates that behavior and is based on this Crunchy Data blog post.