Insert Records Into a Xata Database

To insert a record, you can send a POST request to the /data endpoint under the table resource, at a URL like this: POST https://{your_workspace_slug}.xata.sh/db/{database_name}:{branch_name}/tables/{table_name}/data

In this URL, here's what the {parameters} mean;

  • {your_workspace_slug} refers to the unique ID of your workspace contained within its subdomain. Learn more about this on the workspaces page.
  • {database_name} is the name of your database. Learn more about this on our getting started page.
  • {branch_name} is the name of the branch of your database. Xata supports database branching out of the box, kind of like git. You can learn more about it here. This is usually main for your default/main branch.

The body of the request should be the record in JSON format. For example, to add a new user, you can send the following request:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/tables/users/data

{
  "email": "keanu@example.com",
  "full_name": "Keanu Reeves"
}

The response will be have a status code of 201 with response with a body like this:

{
  "id": "rec_c8hnbch26un1nl0rthkg",
  "xata": {
    "version": 0
  }
}

In the above:

  • id is 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.version is the version of the record. It is automatically incremented any time the record is updated and can be used for optimistic locking.

Inserting a Record with a Linked Field

In the schema that we chose, the teams table has an owner 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. For example:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/tables/teams/data

{
  "name": "Matrix",
  "owner": "rec_c8hnbch26un1nl0rthkg"
}

This creates a team with an ID that you receive in the response:

{
  "id": "rec_c8hng2h26un90p8sr7k0",
  "xata": {
    "version": 0
  }
}

Inserting a Record with Object Columns

In the Xata data model, you can have nested columns similar to JSON. For example, the following insert request contains an address column with two keys:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/tables/users/data

{
  "email": "carrie@example.com",
  "full_name": "Carrie-Anne Moss",
  "address": {
    "street": "123 Main St",
    "zipcode": 12345
  },
  "team": "rec_c8hng2h26un90p8sr7k0"
}

Inserting Records in Bulk

If you have multiple records to insert, it is recommended to use the /bulk endpoint because it provides better performance. The /bulk endpoint recieves an array of records in the "records" key. For example:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/tables/users/bulk

{
  "records": [
    {
      "email": "laurence@example.com",
      "full_name": "Laurence Fishburne",
      "team": "rec_c8hng2h26un90p8sr7k0"
    },
    {
      "email": "hugo@example.com",
      "full_name": "Hugo Weaving",
      "team": "rec_c8hng2h26un90p8sr7k0"
    },
    {
      "email": "joe@example.com",
      "full_name": "Joe Pantoliano",
      "team": "rec_c8hng2h26un90p8sr7k0"
    }
  ]
}

The IDs of each of the newly created records are returned in the response, in the recordIDs key:

{
  "recordIDs": [
    "rec_c8hnnh126unff00ifhhg",
    "rec_c8hnnh126unff00ifhi0",
    "rec_c8hnnh126unff00ifhig"
  ]
}

Next Steps

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.


Last modified 1 mo1 day ago