# Documents

> UStore for Mojo

`from ustore import FieldType, Modification, Gist, …`

## FieldType

The type of a document, or of a value extracted from one, `ustore_docs_field_type_t`.

```mojo
struct FieldType
```

- `JSON` = `FieldType(Int32(0))`: JSON text.
- `NULL` = `FieldType(Int32(10))`: The JSON null.
- `BOOL` = `FieldType(Int32(11))`: A boolean.
- `UUID` = `FieldType(Int32(12))`: A 128-bit UUID.
- `F16` = `FieldType(Int32(40))`: A 16-bit float.
- `F32` = `FieldType(Int32(41))`: A 32-bit float.
- `F64` = `FieldType(Int32(42))`: A 64-bit float.
- `I8` = `FieldType(Int32(20))`: A signed 8-bit integer.
- `I16` = `FieldType(Int32(21))`: A signed 16-bit integer.
- `I32` = `FieldType(Int32(22))`: A signed 32-bit integer.
- `I64` = `FieldType(Int32(23))`: A signed 64-bit integer.
- `U8` = `FieldType(Int32(30))`: An unsigned 8-bit integer.
- `U16` = `FieldType(Int32(31))`: An unsigned 16-bit integer.
- `U32` = `FieldType(Int32(32))`: An unsigned 32-bit integer.
- `U64` = `FieldType(Int32(33))`: An unsigned 64-bit integer.
- `BINARY` = `FieldType(Int32(50))`: The text of a value without a null terminator.
- `STRING` = `FieldType(Int32(51))`: A value printed as text.
- `code` `c_int`: The raw `ustore_docs_field_type_t` value the ABI exchanges.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## Modification

The modification a documents write applies, `ustore_docs_modification_t`.

```mojo
struct Modification
```

- `UPSERT` = `Modification(Int32(0))`: Insert or replace.
- `UPDATE` = `Modification(Int32(1))`: Replace an existing document or field.
- `INSERT` = `Modification(Int32(2))`: Insert a document or field that does not exist yet.
- `PATCH` = `Modification(Int32(3))`: Apply an RFC 6902 patch.
- `MERGE` = `Modification(Int32(4))`: Apply an RFC 7386 merge.
- `code` `c_int`: The raw `ustore_docs_modification_t` value the ABI exchanges.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## Gist

The unique paths to the leaves of the requested documents, read in place from the arena a gist borrows.

```mojo
struct Gist[origin: MutOrigin]
```

- `origin` (comptime): The arena the paths live in, which this result borrows.

- `Written` = `GistWritten`
- `arena` `Pointer[Arena, origin]`: The arena holding the paths.
- `generation` `Int`: The arena's call the paths came from.
- `written` `GistWritten`: The views the engine wrote.

Conforms to: `Answer`, `Deinitable`, `Movable`, `Sized`

## __init__

```mojo
def __init__(out self, arena: Int, generation: Int, written: GistWritten, count: Int)
```

## __len__

The unique paths.

```mojo
def __len__(self) -> Int
```

## fields

The paths as JSON Pointers.

```mojo
def fields(self) -> Tape[origin]
```

## Column

One gathered field over every document, as an Apache Arrow array of its type.

```mojo
struct Column[origin: MutOrigin]
```

- `origin` (comptime): The arena the column lives in, which this result borrows.

- `arena` `Pointer[Arena, origin]`: The arena holding the column.
- `generation` `Int`: The arena's call the column came from.
- `view` `ColumnViewArguments`: The bitmaps, scalars and strings the engine wrote.
- `count` `Int`: Rows, one per document.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `Sized`

## __len__

The rows, one per document.

```mojo
def __len__(self) -> Int
```

## valid

Whether the row's value was found and converted.

```mojo
def valid(self, row: Int) -> Bool
```

## converted

Whether the conversion changed the row's semantics, as parsing a string into an integer does.

```mojo
def converted(self, row: Int) -> Bool
```

## collides

Whether a value of an inconvertible type sits under the field in that row.

```mojo
def collides(self, row: Int) -> Bool
```

## scalars

The scalars of a scalar column, read as `dtype`, which must match the requested type's width.

```mojo
def scalars[dtype: DType](ref self) -> Span[Scalar[dtype], origin_of(self)]
```

## strings

The strings of a string column.

```mojo
def strings(self) -> Tape[origin]
```

## Columns

Every gathered field of every document, one column per field, read in place from the arena a gather borrows.

```mojo
struct Columns[origin: MutOrigin]
```

- `origin` (comptime): The arena the columns live in, which this result borrows.

- `Written` = `ColumnsWritten`
- `arena` `Pointer[Arena, origin]`: The arena holding the columns.
- `generation` `Int`: The arena's call the columns came from.
- `written` `ColumnsWritten`: The views the engine wrote.
- `count` `Int`: Rows, one per document.

Conforms to: `Answer`, `Deinitable`, `Movable`, `Sized`

## __init__

```mojo
def __init__(out self, arena: Int, generation: Int, written: ColumnsWritten, count: Int)
```

## __len__

The columns, one per field.

```mojo
def __len__(self) -> Int
```

## column

The column of field `field`.

```mojo
def column(self, field: Int) -> Column[origin]
```

## DocsWriteConfig

Where inside the documents a write lands, how its values read, and how it applies.

```mojo
struct DocsWriteConfig[fields_origin: ImmOrigin = ImmUntrackedOrigin, id_origin: ImmOrigin = ImmUntrackedOrigin]
```

- `fields_origin` (comptime): The borrowed fields.
- `id_origin` (comptime): The borrowed name of the key field.

- `fields` `StringsView[fields_origin]`: Fields to modify inside the documents, one per task; zeroed modifies whole documents.
- `id_field` `BytesView[id_origin]`: Field holding every document's key when no keys are given, such as "_id".
- `type` `FieldType`: Format of the written values.
- `modification` `Modification`: Modification applied to every document.
- `durability` `Durability`: How durable the writes are once the call finishes at the head.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Names only the knobs that differ from the defaults.

```mojo
def __init__(
    out self,
    *,
    fields: StringsView[fields_origin] = StringsView(),
    id_field: BytesView[id_origin] = BytesView(),
    type: FieldType = FieldType.JSON,
    modification: Modification = Modification.UPSERT,
    durability: Durability = Durability.BUFFERED
)
```

## DocsReadConfig

Where inside the documents a read looks, and what it exports.

```mojo
struct DocsReadConfig[fields_origin: ImmOrigin = ImmUntrackedOrigin]
```

- `fields_origin` (comptime): The borrowed fields.

- `fields` `StringsView[fields_origin]`: Fields to read inside the documents, one per task; zeroed reads whole documents.
- `outputs_type` `FieldType`: Format the values are exported in, [`JSON`](https://www.unum.cloud/docs/ustore/mojo/platform-notes.md#JSON) or [`STRING`](#STRING).
- `values` `Bool`: Whether the bytes come too, or only presences and lengths.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Names only the knobs that differ from the defaults.

```mojo
def __init__(
    out self,
    *,
    fields: StringsView[fields_origin] = StringsView(),
    outputs_type: FieldType = FieldType.JSON,
    values: Bool = True
)
```