# Python values

Custom data types for representing SurrealDB values in Python.

The Python SDK provides custom classes that map SurrealDB types to Python. These classes are used throughout the SDK for parameters and return values. Standard Python types like `str`, `int`, `float`, `bool`, `None`, `bytes`, `dict`, and `list` are also used directly where they map naturally to SurrealDB types.

## `Value` type {#value}

The `Value` union type represents any value that can be sent to or received from SurrealDB.

```python title="Type Definition"
Value = (
    str | int | float | bool | None | bytes | UUID | Decimal
    | Table | Range | RecordID | Duration | Datetime
    | GeometryPoint | GeometryLine | GeometryPolygon
    | GeometryMultiPoint | GeometryMultiLine | GeometryMultiPolygon
    | GeometryCollection | dict[str, "Value"] | list["Value"]
)
```

## Type mapping {#type-mapping}

| Python Type | SurrealDB Type | Notes |
|---|---|---|
| `str` | `string` | |
| `int` | `int` | |
| `float` | `float` | |
| `bool` | `bool` | |
| `None` | `NONE` / `NULL` | |
| `bytes` | `bytes` | |
| `UUID` | `uuid` | From `uuid` standard library |
| `Decimal` | `decimal` | From `decimal` standard library |
| `dict` | `object` | Keys must be strings |
| `list` | `array` | |
| [`RecordID`](/docs/reference/python/api/values/record-id.md) | `record` | Table name + identifier |
| [`Table`](/docs/reference/python/api/values/table.md) | table reference | Table name wrapper |
| [`Duration`](/docs/reference/python/api/values/duration.md) | `duration` | Nanosecond precision |
| [`Datetime`](/docs/reference/python/api/values/datetime.md) | `datetime` | ISO 8601 string |
| [`Range`](/docs/reference/python/api/values/range.md) | `range` | Inclusive/exclusive bounds |
| [`Geometry*`](/docs/reference/python/api/values/geometry.md) | `geometry` | GeoJSON-compatible types |

## `RecordIdType` type {#recordidtype}

Many SDK methods accept a `RecordIdType`, which allows passing a table name, a `Table` object, or a `RecordID`.

```python title="Type Definition"
RecordIdType = str | Table | RecordID
```

## `Tokens` type {#tokens}

Authentication methods return a `Tokens` string alias.

```python title="Type Definition"
Tokens = str
```

## Custom types

- [`RecordID`](/docs/reference/python/api/values/record-id.md) - Record identifier with table name and ID components
- [`Table`](/docs/reference/python/api/values/table.md) - Table name wrapper for type-safe references
- [`Datetime`](/docs/reference/python/api/values/datetime.md) - Datetime wrapper for SurrealDB datetime values
- [`Duration`](/docs/reference/python/api/values/duration.md) - Duration with nanosecond precision and unit conversion
- [`Range`](/docs/reference/python/api/values/range.md) - Range type with inclusive and exclusive bounds
- [`Geometry`](/docs/reference/python/api/values/geometry.md) - GeoJSON-compatible geometry types for spatial data

---

## See also

- [Surreal](/docs/reference/python/api/core/surreal.md) - Connection and query methods
- [Errors](/docs/reference/python/api/errors.md) - Error classes reference