---
title: Identifiers: Default and Custom
slug: v4-4/PVmJjcZeQTvT3toU3rIxo
docTags: 
createdAt: 2023-08-14T14:25:32.351Z
---

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). 

:::CodeblockTabs
pseudocode

```javascript
const docID = await ditto.store.collection('people').upsert({
  name: 'Susan',
  age: 31,
})
console.log(docID) // Auto-generated UUID is: "507f191e810c19729de860ea"
```
:::

Following are the main features and qualities associated with the `_id` field: 

- Document Identification: The document `_id` field serves as the primary key identifying the document in Ditto. For more information, see [Primary key](./#primary-key), as follows. 

- Customizable Primary Key: If preferred, you can customize the primary key as a `string` or JSON `blob` object. For more information, see [Custom Configuration](./#custom-configurations).

- Retrieval by `_id`: Using the Find By ID method, you can fetch a document by its primary key. For more information, see [Fetching a Document by \_id](./#fetching-a-document-by-id).

# Primary Key

The first set of fields within each document uniquely identifies the data that its document object encodes. When grouped in a collection, this `_id` serves as the primary key identifying the document in the collection. 

In addition, you can improve organization, enhance querying capabilities, and establish specific relationships, using a combination of two or more fields to form a more specific and meaningful *composite key*. It is important to note there are distinct tradeoffs that you must closely consider before choosing to create a composite key. 

For more information, see [Custom Configurations](./#custom-configurations) , as follows.

## Custom Configurations

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

:::hint{type="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.
:::

### Supplying a String ID

The following snippet demonstrates creating a new document assigned the string value `123abc`.

:::CodeblockTabs
pseudocode

```javascript
const docID = await ditto.store.collection('cars').upsert({
  _id: '123abc',
  name: 'Susan',
  age: 31,
})

console.log(docID) // "123abc"
```

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

### Forming a Composite Key

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.

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.

The following snippet demonstrates combining the `user_id` and `work_id` fields to form the `123abc780` composite key:

:::CodeblockTabs
pseudocode

```javascript
const docID = await ditto.store.collection('cars').upsert({
 _id: {
    user_id: "123abc",
    work_id: 789
  }
})

console.log(docID) // "123abc789"
```

```curl
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
        }
      }]
  }'
```
:::

## Fetching a Document by \_id

Fetch a single document by its primary key: the document `_id`field by invoking the Find By ID method.

:::CodeblockTabs
pseudocode

```javascript
const document = await ditto.store
.collection("cars")
.findById("123456")
```
:::