Creating records
You can create a record like this:
const record = await xata.db.Users.create({
email: 'keanu@example.com',
name: 'Keanu Reeves'
});
record = xata.records().insert("Users", {
"email": "keanu@example.com",
"name": "Keanu Reeves"
})
client, _ := xata.NewRecordsClient()
record, _ := client.Insert(context.TODO(), xata.InsertRecordRequest{
RecordRequest: xata.RecordRequest{
TableName: "Users",
},
Body: map[string]*xata.DataInputRecordValue{
"email": xata.ValueFromString("keanu@example.com"),
"name": xata.ValueFromString("Keanu Reeves"),
},
})
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
{
"statement": "INSERT INTO \"Users\" (email,name) VALUES ($1,$2) RETURNING *;",
"params": ["keanu@example.com", "Keanu Reeves"]
}
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/data
{
"email": "keanu@example.com",
"name": "Keanu Reeves"
}
The create method fails if the record ID already exists.
The SDK returns the created record and the response looks like the following:
{
"email": "keanu@example.com",
"id": "rec_cd8rqcoavc42pi67lgd0",
"name": "Keanu Reeves",
"bio": NULL,
"address": NULL,
}
{
"id": "rec_c8hnbch26un1nl0rthkg",
"xata": {
"version": 0,
"createdAt": "2023-05-15T08:21:31.96526+01:00",
"updatedAt": "2023-05-15T21:58:54.072595+01:00"
}
}
{
"records": [
{
"id": "rec_c8hnbch26un1nl0rthkg",
"xata": {
"version": 0,
"createdAt": "2023-05-15T08:21:31.96526+01:00",
"updatedAt": "2023-05-15T08:21:31.96526+01:00"
}
}
]
}
{
"id": "rec_c8hnbch26un1nl0rthkg",
"xata": {
"version": 0,
"createdAt": "2023-05-15T08:21:31.96526+01:00",
"updatedAt": "2023-05-15T21:58:54.072595+01:00"
}
}
In the above the API returns a special set of columns:
idis the ID of the record, which Xata generates automatically. The generated records are globally unique and sortable. This means that sorting by the IDs you sort by the insertion order.xata.versionis the version of the record. It is automatically incremented any time the record is updated and can be used for optimistic locking.xata.createdAtis the timestamp when the record was created.xata.updatedAtis the timestamp of last record update.
If you want to return more columns, you can specify them via the columns parameter.
If you want to specify your own ID, you can do it like this:
const record = await xata.db.Users.create('myid', {
email: 'keanu@example.com',
name: 'Keanu Reeves'
});
record = xata.records().insert_with_id("Users", "myid", {
"email": "keanu@example.com",
"name": "Keanu Reeves"
})
client, _ := xata.NewRecordsClient()
record, err := client.InsertWithID(context.TODO(), xata.InsertRecordWithIDRequest{
RecordRequest: xata.RecordRequest{
TableName: "Users",
},
RecordID: "myid",
Body: map[string]*xata.DataInputRecordValue{
"email": xata.ValueFromString("keanu@example.com"),
"name": xata.ValueFromString("Keanu Reeves"),
},
})
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
{
"statement": "INSERT INTO \"Users\" (id,email,name) VALUES ($1,$2,$3) RETURNING *;",
"params": ["myid", "keanu@example.com", "Keanu Reeves"]
}
// PUT https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/data/{record_id}?createOnly=true
{
"email": "keanu@example.com",
"name": "Keanu Reeves"
}
In the REST API example, note the change from POST to PUT. The createOnly query parameter signals Xata to return an error in case a record with the given ID already exists.
In the schema that we chose, the Posts table has an author column of type link that links to the Users table. To insert a record with a linked field, use the ID of the target record in the link column.
const record = await xata.db.Posts.create({
title: 'Filming the Matrix',
author: 'rec_cd8rqcoavc42pi67lgd0'
});
record = xata.records().insert("Posts", {
"title": "Filming the Matrix",
"author": "rec_cd8rqcoavc42pi67lgd0"
})
client, _ := xata.NewRecordsClient()
record, _ := client.Insert(context.TODO(), xata.InsertRecordRequest{
RecordRequest: xata.RecordRequest{
TableName: "Users",
},
Body: map[string]*xata.DataInputRecordValue{
"title": xata.ValueFromString("Filming the Matrix"),
"author": xata.ValueFromString("rec_cd8rqcoavc42pi67lgd0"),
},
})
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
{
"statement": "INSERT INTO \"Posts\" (title,author) VALUES ($1,$2) RETURNING *;",
"params": ["Filming the Matrix", "rec_cd8rqcoavc42pi67lgd0"]
}
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/data
{
"title": "Filming the Matrix",
"author": "rec_cd8rqcoavc42pi67lgd0"
}
If you have multiple records to insert, you can send them in a single request via the /bulk endpoint. For example:
const users = await xata.db.Users.create([
{
email: 'laurence@example.com',
name: 'Laurence Fishburne',
team: 'rec_cd8s4kbo8dsvsjilo1ug'
},
{
email: 'hugo@example.com',
name: 'Hugo Weaving',
team: 'rec_cd8s4kbo8dsvsjilo1ug'
},
{
email: 'joe@example.com',
name: 'Joe Pantoliano',
team: 'rec_cd8s4kbo8dsvsjilo1ug'
}
]);
users = xata.records().bulk_insert("Users", {
"records": [
{
"email": "laurence@example.com",
"name": "Laurence Fishburne",
"team": "rec_cd8s4kbo8dsvsjilo1ug"
},
{
"email": "hugo@example.com",
"name": "Hugo Weaving",
"team": "rec_cd8s4kbo8dsvsjilo1ug"
},
{
"email": "joe@example.com",
"name": "Joe Pantoliano",
"team": "rec_cd8s4kbo8dsvsjilo1ug"
}
]
})
client, _ := xata.NewRecordsClient()
users, _ := client.BulkInsert(context.TODO(), xata.BulkInsertRecordRequest{
RecordRequest: xata.RecordRequest{
TableName: "Users",
},
Columns: []string{"name"},
Records: []map[string]*xata.DataInputRecordValue{
{
"email": xata.ValueFromString("laurence@example.com"),
"name": xata.ValueFromString("Laurence Fishburne"),
"team": xata.ValueFromString("rec_cd8s4kbo8dsvsjilo1ug"),
},
{
"email": xata.ValueFromString("hugo@example.com"),
"name": xata.ValueFromString("Hugo Weaving"),
"team": xata.ValueFromString("rec_cd8s4kbo8dsvsjilo1ug"),
},
{
"email": xata.ValueFromString("joe@example.com"),
"name": xata.ValueFromString("Joe Pantoliano"),
"team": xata.ValueFromString("rec_cd8s4kbo8dsvsjilo1ug"),
},
},
})
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
{
"statement": "INSERT INTO \"Users\" (email,name,team) VALUES ($1,$2,$3),($4,$5,$6),($7,$8,$9) RETURNING *;",
"params": [
"laurence@example.com",
"Laurence Fishburne",
"rec_cd8s4kbo8dsvsjilo1ug",
"hugo@example.com",
"Hugo Weaving",
"rec_cd8s4kbo8dsvsjilo1ug",
"joe@example.com",
"Joe Pantoliano",
"rec_cd8s4kbo8dsvsjilo1ug"
]
}
// POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/bulk
{
"records": [
{
"email": "laurence@example.com",
"name": "Laurence Fishburne",
"team": "rec_cd8s4kbo8dsvsjilo1ug"
},
{
"email": "hugo@example.com",
"name": "Hugo Weaving",
"team": "rec_cd8s4kbo8dsvsjilo1ug"
},
{
"email": "joe@example.com",
"name": "Joe Pantoliano",
"team": "rec_cd8s4kbo8dsvsjilo1ug"
}
]
}
The bulk create method fails if the record ID already exists.
It is possible to provide IDs for each of the records. If records with the same IDs already exist, the bulk operation is canceled and an error is returned.
The file and file[] (file array) columns are not permitted in bulk requests.
Great! We can insert data into our databases. Let's now explore how we get data from a database. Alternatively, we can also look into updating data or deleting data. We've got guides for each of these operations.