Skip to content

Create

Info

For simplicity, all the examples on this page, assume the HTTP client is already initialized and the requests are unauthenticated.

For an example of how to initialize the HTTP clients and make authenticated requests see authentication section

Creating (inserting) rows is performed by issuing POST requests.

Insert one row

curl -X POST -d '{"todo":"new todo"}' \
http://localhost:8080/rest/todos
await fetch(endpoint+'/rest/todos', {
    method: 'POST',
    body: JSON.stringify({todo:'new todo'})
});
await client.post('/rest/todos', {todo:'New todo'});
await client.query({ 
    query: gql`
        mutation {
            insert {
                todo(input: {todo: "new todo"}) {
                    id todo
                }
            }
        }
    `
});

Insert multiple rows

curl -X POST \
-d '[{"todo":"todo one"}, {"todo":"todo two"}]' \
http://localhost:8080/rest/todos
await fetch(endpoint+'/rest/todos', {
    method: 'POST',
    body: JSON.stringify([{"todo":"todo one"}, {"todo":"todo two"}])
});
await client.post('/rest/todos', [{"todo":"todo one"}, {"todo":"todo two"}]);
await client.query({ 
    query: gql`
        mutation {
            insert {
                todos(input: [{"todo":"todo one"}, {"todo":"todo two"}]) {
                    id
                }
            }
        }
    `
});

columns= parameter

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.

Info

when performing bulk inserts, it's often a good idea to specify columns parameter even if all the json fields need to be considered. The reason is that by providing this parameter, subZero no longer needs to parse the (big) json payload to determine it's columns but can send it directly to PostgreSQL

Receive the inserted row columns

In many cases, when inserting rows, it's desired to receive in the response some columns of the newly inserted rows, especially columns that are generated on the server side like id or created_at.

To achieve this result one must include the Prefer: return=representation header with the POST request. In almost all cases, this header is used in combination with the select query parameter to avoid fetching all the columns of the newly inserted row.

curl -X POST \
-H 'Prefer: return=representation' \
-d '{"todo":"new todo"}' \
http://localhost:8080/rest/todos?select=id,created_at
await fetch(endpoint+'/rest/todos?select=id,created_at', {
    method: 'POST',
    headers: new Headers({'Prefer': 'return=representation'})},
    body: JSON.stringify({"todo":"new todo"})
});
const options = {headers: {'Prefer': 'return=representation'}}
await client.post('/rest/todos?select=id,created_at', {"todo":"new todo"}, options);
await client.query({ 
    query: gql`
        mutation {
            insert {
                todo(input: {todo: "new todo"}) {
                    id created_at
                }
            }
        }
    `
});

When inserting a single row, in order to receive back a json object representing the row (instead of a json array with a single item) include the Accept: application/vnd.pgrst.object+json header.

curl -X POST \
-H 'Prefer: return=representation' \
-H 'Accept: application/vnd.pgrst.object+json' \
-d '{"todo":"new todo"}' \
http://localhost:8080/rest/todos?select=id,created_at
await fetch(endpoint+'/rest/todos?select=id,created_at', {
    method: 'POST',
    headers: new Headers({'Prefer': 'return=representation', 'Accept': 'application/vnd.pgrst.object+json'})},
    body: JSON.stringify({"todo":"new todo"})
});
const options = {headers: {'Prefer': 'return=representation', 'Accept': 'application/vnd.pgrst.object+json'}}
await client.post('/rest/todos?select=id,created_at', {"todo":"new todo"}, options);
await client.query({ 
    query: gql`
        mutation {
            insert {
                todo(input: {todo: "new todo"}) {
                    id created_at
                }
            }
        }
    `
});