---
title: Data
description: Couchbase Server saves data as items, each of which has a key and a value.
pubDate: 2026-10-03T04:27:21.374Z
meta:
  component:
    title: Couchbase Server
    version: "8.0"
antora:
  editUrl: https://github.com/couchbase/docs-server/edit/release/8.0/modules/learn/pages/data/data.adoc
  xref: xref:server:learn:data/data.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/server/current/learn/data/data.html)

# Data

> Couchbase Server saves data as items, each of which has a key and a value. 

## [](#items-keys-and-values)Items, Keys, and Values

Each item consists of a key and a value. Each key is unique within its collection, and values can be either binary or JSON.

All items are handled by Couchbase Server's [Data Service](../services-and-indexes/services/data-service.md). All JSON items must be encoded as specified in [RFC 8259](https://tools.ietf.org/html/rfc8259). Binary items can have any encoding.

## [](#keys)Keys

Each value (binary or JSON) is identified by a unique key, defined by the user or application when the item is saved. The key is immutable: once the item is saved, the key cannot be changed.

> [!NOTE]
> Couchbase also refers to an item's key as its `id`.

Each key:

* Can consist of any string of bytes, but should preferably consist of a UTF-8 string with no spaces (to make sure the key's acceptability to all Couchbase-Server services). Special characters such as `(`, `%`, `/`, `"`, and `_`, are acceptable.
* Must be 246 bytes or less.  
> [!NOTE]  
> If a user accesses the `default` collection (for example, by setting the query context to the default collection in the default scope, or by using a legacy SDK), then the key can be up to 250 bytes in length. This is to maintain compatibility with earlier versions of Couchbase.
* Must be unique within a collection.

## [](#values)Values

The maximum size of a value is 20 MiB. A value can be either:

* **Binary**: any form of binary is acceptable.  
> [!NOTE]  
> A binary value cannot be parsed, indexed, or queried: it can only be retrieved by key.
* **JSON**: a JSON value, referred to as a `document`, can be parsed, indexed, and queried. Each document consists of 1 or more attributes, each of which has its own value. An attribute's value can be a basic type (such as a number, string, or Boolean), or a complex type, such as an embedded document or an array.

## [](#document-structure)Document Structure

A sample JSON document is provided below. Its contents are as follows:

* `a1` and `a2` are attributes that respectively have a single number and a single string as their values.
* `a3` is an attribute whose value is an embedded document consisting of a single attribute, `b1`, whose own value is an array of 3 numbers.
* `a4` is an attribute whose value is an array of 2 documents, each document consisting of an attribute (`c1` or `c2`) whose own values are respectively a string and a number.

```json
{
  "a1" : number,
  "a2" : "string",
  "a3" : {
    "b1" : [ number, number, number ]
    },
  "a4" : [
    { "c1" : "string", "c2" : number },
    { "c1" : "string", "c2" : number }
  ]
}
```

> [!NOTE]
> The official JSON definition is provided at [RFC 7159](https://tools.ietf.org/html/rfc7159), and at [ECMA 404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).

The benefits offered to application programmers by JSON are considered in [The Couchbase Data Model](document-data-model.md).

## [](#sub-documents-overview)Sub-Documents

A `Sub-Document` is an inner component of a JSON document. The Sub-Document is referred to by a `path`, which specifies attributes and array-positions.

The example given above includes the following paths:

* `a1`, whose value is a number.
* `a3.b1`, whose value is an array of numbers.
* `a3.b1[0]`, whose value is the first number in an array.
* `a4[1].c2`, whose value is a number.

The Couchbase SDK provides a Sub-Document API, which allows paths to be specified, and sub-documents thereby read and written to. This makes it unnecessary to transfer entire documents across the network when only partial modifications are required, potentially providing significant improvements in network performance. For further information, see [Sub-Document Operations](../../../../java-sdk/current/howtos/subdocument-operations.md).

## [](#metadata)Metadata

`Metadata` is automatically generated and stored for each item saved in Couchbase Server. The following document, which contains airport-information, has been saved with the key `airport_1306`:

```json
{
  "airportname": "Brienne Le Chateau",
  "city": "Brienne-le Chateau",
  "country": "France",
  "faa": null,
  "geo": {
    "alt": 381,
    "lat": 48.429764,
    "lon": 4.482222
  },
  "icao": "LFFN",
  "id": 1306,
  "type": "airport",
  "tz": "Europe/Paris"
}
```

Couchbase Server generates metadata in association with the document when the document is saved. The metadata might be as follows:

```json
{
  "meta": {
    "id": "airport_1306",
    "rev": "1-1526338d1bbb00000000000002000000",
    "expiration": 0,
    "flags": 33554432,
    "type": "json"
  },
  "xattrs": {}
}
```

The attributes within the metadata are:

* `meta`: the attribute whose value is the standard metadata for the saved document, `airport_1306`.
* `id`: the key of the saved document, which is `airport_1306`.
* `rev`: the `revision` or `sequence number`. This value is for internal server-use only: it's used in the resolution of conflicts that occur when replicated documents are updated concurrently on different servers, representing the number of times the document has been mutated. For more information, see [XDCR Conflict Resolution](../clusters-and-availability/xdcr-conflict-resolution.md).
* `expiration`: the expiration-time (or `Time to Live`) of the document. If non-zero, it determines when Couchbase Server removes the document. You can set the expiration explicitly on a document or automatically by using by the `maxTTL` setting on the collection or bucket containing it. See [Expiration](expiration.md) for more information.
* `flags`: Couchbase SDK-specific values that may be used to identify the type of data saved or to specify formatting.
* `type`: the type of the saved value, which in this case is `json`.
* `xattrs`: extended attributes which constitute a special kind of metadata, some of which is system-internal, some of which can optionally be written and read by user-applications. See [Extended Attributes](extended-attributes-fundamentals.md) for more information.

## [](#size-limits)Size Limits

The following diagram indicates the respective maximum component sizes of a Couchbase Server data-item.

![item maximum sizes](../_images/data/item-maximum-sizes.png)