# Documents

> UStore for Python

`docs_write`, `docs_read`, `docs_gist` and `docs_gather` address JSON documents, whole or a field inside each, where a field is a top-level key or a JSON Pointer such as `/user/name`.
A document is JSON text or bytes, a tape of them, or a dict, list or number the binding serializes, and `Collection.docs` takes and answers Python objects outright.
A fixed-width `type` given a contiguous buffer writes a column of scalars, one per key, so a NumPy column of floats or integers reaches the store without being printed as JSON and parsed back.
A gather answers the same shapes in reverse: an `f16` column carries the `e` format, which NumPy reads as `float16` without a copy, and a `uuid` column carries sixteen bytes per document.
`Table.to_pandas` takes a `page`, converting that many rows at a time so only one page of gathered columns is ever live.

`import ustore`

`from ustore import Columns`

## FieldType

How a document or a field is spelled, or what a gather converts it into, valued as `ustore_docs_field_type_t`.

```python
class FieldType(IntEnum)
```

- `JSON` = `0`
- `NULL` = `10`
- `BOOL` = `11`
- `UUID` = `12`
- `I8` = `20`
- `I16` = `21`
- `I32` = `22`
- `I64` = `23`
- `U8` = `30`
- `U16` = `31`
- `U32` = `32`
- `U64` = `33`
- `F16` = `40`
- `F32` = `41`
- `F64` = `42`
- `BINARY` = `50`
- `STRING` = `51`

## Modification

What a document write applies, valued as `ustore_docs_modification_t`.

```python
class Modification(IntEnum)
```

- `UPSERT` = `0`
- `UPDATE` = `1`
- `INSERT` = `2`
- `PATCH` = `3`
- `MERGE` = `4`

## DocsView

The JSON documents of a collection as Python objects, serialized and parsed in C.

```python
class DocsView
```

## DocsJSONView

The JSON documents of a collection as their text: one key reads a copy as bytes, a batch a list of them.

```python
class DocsJSONView
```

## JSONValue

```python
type JSONValue = dict[str, JSONValue] | list[JSONValue] | tuple[JSONValue, ...] | str | int | float | bool | None
```

## DocumentLike

```python
type DocumentLike = str | Buffer | dict[str, JSONValue] | list[JSONValue] | int | float | bool
```

## Columns

The typed columns one gather wrote into an [`Arena`](https://www.unum.cloud/docs/ustore/python/batches-and-arenas.md#Arena), viewing it until it rewinds.

```python
class Columns
```

## validities

The bitmap of documents whose value was found and converted.

```python
def validities(field: int) -> memoryview
```

## conversions

The bitmap of values whose conversion changed their meaning.

```python
def conversions(field: int) -> memoryview
```

## collisions

The bitmap of values of a type no conversion reaches.

```python
def collisions(field: int) -> memoryview
```

## types

```python
types: tuple[FieldType, ...]
```

## rows

```python
rows: int
```