> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents and IDs (Legacy)

> Ditto is a NoSQL database that organizes JSON-like documents into collections. Unlike JSON, with Ditto you can apply updates directly to the document, ensuring sync across all connected peers.

Additionally, it offers support for various data types. For an overview of the data types you can use in Ditto, see the *Platform Manual* [Data Structures and Types](/key-concepts/document-model).

A document serves as a schema-flexible unit of data. If collections are compared to tables, a document can be compared to a row. Each document at its core is a map capable of holding fields and embedded key-value pairs.

Every document is assigned a primary key, referred to as a *document ID*.

For more information about Ditto documents, see *Platform Manual* [Document Model](/key-concepts/document-model).

## Primary Key: Document ID

The Ditto query engine supports various filter operations for optimal data retrieval.

As the basis of data organization and access in Ditto, the query engine indexes the document ID so you can quickly and precisely access your data.

When invoking the Upsert method to create a new document, unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID).

<Info>
  When referencing the document ID in your queries for the HTTP API, pass `id` instead of the reserved `_id` parameter. However, if not making API calls, pass the reserved `_id` instead.
</Info>

### Custom Document ID

If supplying your own document ID, you can encode your value in a `string` or, if forming a composite key, a JSON-object.

<Warning>
  You can configure a custom document ID only at the time of document creation.

  Once a document is created, to ensure consistency and uniqueness throughout the platform, the unique identifier that either Ditto automatically generated and assigned or you manually assigned becomes permanent and cannot be changed at a later time.
</Warning>

The decision to opt for a composite key depends on your specific use case. Following are typical use cases for forming a composite key:

* To implement additional logic to handle (or prevent) duplicate writes.

* To simplify queries and enhance efficiency in the querying process.

### Supplying a String ID

To provide a custom document ID, when invoking `upsert` to create a new document, include the `id` parameter with a `string` set to the value you want to use as the document's ID.

For example, the following snippet demonstrates creating a new document in the `people` collection with the custom ID set to `abc123`, along with the specified `name` and `age` values:

```bash cURL theme={null}
curl -X POST 'https://<CLOUD_ENDPOINT>/api/v4/store/write' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "commands": [{
        "method": "upsert",
        "collection": "people",
        "id": "abc123",
        "value": {
          "name": "Susan", "age": 31
        }
      }]
  }'
```

### Forming a Composite Key

To form a composite key, when calling `upsert` to create a new document, pass the fields you want to combine to form the new primary key in an embedded `map` structure under the `id` field.

For example, the following snippet shows an `upsert` operation on the `people` collection forming a composite key made up of two parts:

* `string`
* `integer`

<Info>
  Ditto compares document IDs based on the combination of keys and their corresponding values, not by literal order in which the key-value pairs are defined.

  Therefore, if two document IDs have the same key-value pairs, they will be considered equal. For example:
  `{a: "foo", b: 1} == { b: 1, a: "foo" }`
</Info>

```bash cURL theme={null}
curl -X POST 'https://<CLOUD_ENDPOINT>/api/v4/store/write' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      [{
        "method": "upsert",
        "collection": "people",
        "id": {
          "user_id": "456abc",
          "work_id": 789
        },
        "value": {
          "name": "Susan",
          "age": 31
        }
      }]
  }'
```