Light
Dark
System
v4latest
v5dev
v4latest
v3
v2
v1

API/Protocol

A codec knows how to work with the internal binary data from EdgeDB. The binary protocol specification for the codecs can be found in the relevant part of the EdgeDB documentation. Useful links for codec developers:

Copy
@type EdgeDB.Protocol.Codec.id() :: bitstring()

Codec ID.

Copy
@type EdgeDB.Protocol.Codec.t() :: term()

All the types that implement this protocol.

Copy
@spec EdgeDB.Protocol.Codec.decode(t(), bitstring(), EdgeDB.Protocol.CodecStorage.t()) :: value when value: term()

Function that can decode EdgeDB binary format into an entity.

Copy
@spec EdgeDB.Protocol.Codec.encode(t(), value, EdgeDB.Protocol.CodecStorage.t()) :: iodata() when value: term()

Function that can encode an entity to EdgeDB binary format.

Behaviour for custom scalar codecs.

See custom codecs development guide on hex.pm or on edgedb.com for more information.

A storage for each codec that the connection knows how to decode.

Copy
@type EdgeDB.Protocol.CodecStorage.t() :: :ets.tab()

A storage for each codec that the connection knows how to decode.

Copy
@spec EdgeDB.Protocol.CodecStorage.get(t(), binary()) :: EdgeDB.Protocol.Codec.t() | nil

Find a codec in the storage by ID.

Copy
@spec EdgeDB.Protocol.CodecStorage.get_by_name(t(), binary()) :: EdgeDB.Protocol.Codec.t() | nil

Find a codec in the storage by type name.

Definition for enumerations used in EdgeDB protocol.

Copy
@type EdgeDB.Protocol.Enums.capabilities() :: [capability()]

Query capabilities.

Copy
@type EdgeDB.Protocol.Enums.capability() ::
  :readonly
  | :modifications
  | :session_config
  | :transaction
  | :ddl
  | :persistent_config
  | :all
  | :execute
  | :legacy_execute

Query capabilities.

Values:

  • :readonly - query is read-only.

  • :modifications - query is not read-only.

  • :session_config - query contains session config change.

  • :transaction - query contains start/commit/rollback of transaction or savepoint manipulation.

  • :ddl - query contains DDL.

  • :persistent_config - server or database config change.

  • :all - all possible capabilities.

  • :execute - capabilities to execute query.

Copy
@type EdgeDB.Protocol.Enums.cardinality() :: :no_result | :at_most_one | :one | :many | :at_least_one

Cardinality of the query result.

Values:

  • :no_result - query doesn’t return anything.

  • :at_most_one - query return an optional single elements.

  • :one - query return a single element.

  • :many - query return a set of elements.

  • :at_least_one - query return a set with at least of one elements.

Copy
@type EdgeDB.Protocol.Enums.compilation_flag() ::
  :inject_output_type_ids | :inject_output_type_names | :inject_output_object_ids

Compilation flags for query to extend it’s features.

Values:

  • :inject_output_type_ids - inject __tid__ property as .__type__.id alias into returned objects.

  • :inject_output_type_names - inject __tname__ property as .__type__.name alias into returned objects.

  • :inject_output_object_ids - inject id property into returned objects.

Copy
@type EdgeDB.Protocol.Enums.compilation_flags() :: [compilation_flag()]

Compilation flags for query to extend it’s features.

Copy
@type EdgeDB.Protocol.Enums.output_format() :: :binary | :json | :json_elements | :none

Data output format.

Values:

  • :binary - return data encoded in binary.

  • :json - return data as single row and single field that contains the result set as a single JSON array.

  • :json_elements - return a single JSON string per top-level set element. This can be used to iterate over a large result set efficiently.

  • :none - prevent EdgeDB from returning anything event if EdgeQL query does it.

Light
Dark
System

We use ChatGPT with additional context from our documentation to answer your questions. Not all answers will be accurate. Please join our Discord if you need more help.