Python values

The Python SDK has classes for the SurrealDB values that Python has no type for, such as record IDs, durations and geometry. This section has a page for each class. This page lists those pages, maps each Python type to its SurrealDB type, and shows the Value union that the SDK uses for any value. For a guide to how values convert, with examples, see Value types.

Value classes

• •

  RecordID: RecordID names one record by its table and ID, and StringRecordId names one as SurrealQL text.

• •

  Table: Table names a table, as a CRUD target or a query variable.

• •

  Null: Null is the SurrealDB NULL, which is a different value from None.

• •

  Datetime: Every datetime reads back as a PreciseDatetime, and Datetime sends ISO 8601 text.

• •

  Duration: Duration holds a length of time in nanoseconds.

• •

  SurrealSet: Every set reads back as a SurrealSet, which the SDK writes back as a set.

• •

  Range: Range with BoundIncluded and BoundExcluded holds a span of values or of record IDs.

• •

  Geometry: GeometryPoint and six other classes hold geospatial data.

• •

  File: File refers to a file in a bucket, and FileMetadata describes a stored file.

• •

  Sized numbers and BigDecimal: I8 to U64, F16, F32 and BigDecimal hold the SurrealDB 4.0 number types.

• •

  Dates, times and intervals: PlainDate, PlainTime, Timestamp and Interval hold the SurrealDB 4.0 calendar types.

• •

  Regex: Regex holds a pattern for the SurrealDB 4.0 regex type.

Type mapping

The SDK sends the SurrealDB 4.0 types as their own types only over cbor.2, the format that SurrealDB 4.0 servers speak. Against an earlier server, it sends the nearest type that the server has, and the page for each class says what that is. A datetime.timedelta and a compiled re.Pattern cannot be sent, and raise TypeError.

The Value type

Value is the union of the values that the SDK sends and reads back, and methods use it to annotate data and results. The Python types page explains it in full.

Value = (
    str | int | float | bool | None | NullType
    | bytes | UUID | Decimal
    | Table | Range | RecordID | StringRecordId | File
    | Duration | Datetime
    | BigDecimal | PlainDate | PlainTime | Timestamp | Interval | Regex
    | date | time
    | GeometryPoint | GeometryLine | GeometryPolygon
    | GeometryMultiPoint | GeometryMultiLine | GeometryMultiPolygon
    | GeometryCollection
    | SurrealSet | set[Any] | frozenset[Any]
    | dict[str, "Value"] | list["Value"]
)

RecordIdType

RecordIdType is the union that CRUD methods accept as a target. A str in it is always a table name. Import it from surrealdb.data.types.record_id; the RecordID page has the details.

RecordIdType = str | RecordID | StringRecordId | Table

Tokens

Tokens is the frozen dataclass that signin() and signup() return, with an access token and an optional refresh token. It is documented with the other dataclasses on the Python types page.

See also

• •

  Value types for how values convert, with examples

• •

  Python types for type aliases, options and other dataclasses

• •

  Data types in SurrealQL