<commit_before>.. _ref_proto_typedesc:

================
Type Descriptors
================

This section describes how type information for query input and results
is encoded.  Specifically, this is needed to decode the server response to
the :ref:`ref_protocol_msg_describe_statement` message.

The type descriptor is essentially a list of type information *blocks*:

* each *block* encodes one type;

* *blocks* can reference other *blocks*.

While parsing the *blocks*, a database driver can assemble an
*encoder* or a *decoder* of the EdgeDB binary data.

An *encoder* is used to encode objects, native to the driver's runtime,
to binary data that EdegDB can decode and work with.

A *decoder* is used to decode data from EdgeDB native format to
data types native to the driver.

There is one special type with *type id* of zero:
``00000000-0000-0000-0000-000000000000``. The describe result of this type
contains zero *blocks*. It's used when a statement returns no meaningful
results, e.g. the ``CREATE DATABASE example`` statement.


Set Descriptor
==============

.. code-block:: c

    struct SetDescriptor {
        // Indicates that this is a Set value descriptor.
        uint8   type = 0;

        // Descriptor ID.
        uuid    id;

        // Set element type descriptor index.
        uint16  type_pos;
    };

Set values are encoded on the wire as
:ref:`single-dimensional arrays <ref_protocol_fmt_array>`.


Object Shape Descriptor
=======================

.. code-block:: c

    struct ObjectShapeDescriptor {
        // Indicates that this is an
        // Object Shape descriptor.
        uint8           type = 1;

        // Descriptor ID.
        uuid            id;

        // Number of elements in shape.
        uint16          element_count;

        ShapeElement    elements[element_count];
    };

    struct ShapeElement {
        // Field flags:
        //   1 << 0: the field is implicit
        //   1 << 1: the field is a link property
        //   1 << 2: the field is a link
        uint8           flags;

        // Field name.
        string          name;

        // Field type descriptor index.
        uint16          type_pos;
    };

Objects are encoded on the wire as :ref:`tuples <ref_protocol_fmt_tuple>`.


Base Scalar Type Descriptor
===========================

.. code-block:: c

    struct BaseScalarTypeDescriptor {
        // Indicates that this is an
        // Base Scalar Type descriptor.
        uint8           type = 2;

        // Descriptor ID.
        uuid            id;
    };


The descriptor IDs for base scalar types are constant.
The following table lists all EdgeDB base types descriptor IDs:

.. list-table::
   :header-rows: 1

   * - ID
     - Type

   * - ``00000000-0000-0000-0000-000000000100``
     - :ref:`std::uuid <ref_protocol_fmt_uuid>`

   * - ``00000000-0000-0000-0000-000000000101``
     - :ref:`std::str <ref_protocol_fmt_str>`

   * - ``00000000-0000-0000-0000-000000000102``
     - :ref:`std::bytes <ref_protocol_fmt_bytes>`

   * - ``00000000-0000-0000-0000-000000000103``
     - :ref:`std::int16 <ref_protocol_fmt_int16>`

   * - ``00000000-0000-0000-0000-000000000104``
     - :ref:`std::int32 <ref_protocol_fmt_int32>`

   * - ``00000000-0000-0000-0000-000000000105``
     - :ref:`std::int64 <ref_protocol_fmt_int64>`

   * - ``00000000-0000-0000-0000-000000000106``
     - :ref:`std::float32 <ref_protocol_fmt_float32>`

   * - ``00000000-0000-0000-0000-000000000107``
     - :ref:`std::float64 <ref_protocol_fmt_float64>`

   * - ``00000000-0000-0000-0000-000000000108``
     - :ref:`std::decimal <ref_protocol_fmt_decimal>`

   * - ``00000000-0000-0000-0000-000000000109``
     - :ref:`std::bool <ref_protocol_fmt_bool>`

   * - ``00000000-0000-0000-0000-00000000010A``
     - :ref:`std::datetime <ref_protocol_fmt_datetime>`

   * - ``00000000-0000-0000-0000-00000000010E``
     - :ref:`std::duration <ref_protocol_fmt_duration>`

   * - ``00000000-0000-0000-0000-00000000010F``
     - :ref:`std::json <ref_protocol_fmt_json>`

   * - ``00000000-0000-0000-0000-00000000010B``
     - :ref:`cal::local_datetime <ref_protocol_fmt_local_datetime>`

   * - ``00000000-0000-0000-0000-00000000010C``
     - :ref:`cal::local_date <ref_protocol_fmt_local_date>`

   * - ``00000000-0000-0000-0000-00000000010D``
     - :ref:`cal::local_time <ref_protocol_fmt_local_time>`


Scalar Type Descriptor
======================

.. code-block:: c

    struct ScalarTypeDescriptor {
        // Indicates that this is a
        // Scalar Type descriptor.
        uint8           type = 3;

        // Descriptor ID.
        uuid            id;

        // Parent type descriptor index.
        uint16          base_type_pos;
    };


Tuple Type Descriptor
=====================
<commit_msg>add bigint to basescallar type descritpor ID table<commit_after>.. _ref_proto_typedesc:

================
Type Descriptors
================

This section describes how type information for query input and results
is encoded.  Specifically, this is needed to decode the server response to
the :ref:`ref_protocol_msg_describe_statement` message.

The type descriptor is essentially a list of type information *blocks*:

* each *block* encodes one type;

* *blocks* can reference other *blocks*.

While parsing the *blocks*, a database driver can assemble an
*encoder* or a *decoder* of the EdgeDB binary data.

An *encoder* is used to encode objects, native to the driver's runtime,
to binary data that EdegDB can decode and work with.

A *decoder* is used to decode data from EdgeDB native format to
data types native to the driver.

There is one special type with *type id* of zero:
``00000000-0000-0000-0000-000000000000``. The describe result of this type
contains zero *blocks*. It's used when a statement returns no meaningful
results, e.g. the ``CREATE DATABASE example`` statement.


Set Descriptor
==============

.. code-block:: c

    struct SetDescriptor {
        // Indicates that this is a Set value descriptor.
        uint8   type = 0;

        // Descriptor ID.
        uuid    id;

        // Set element type descriptor index.
        uint16  type_pos;
    };

Set values are encoded on the wire as
:ref:`single-dimensional arrays <ref_protocol_fmt_array>`.


Object Shape Descriptor
=======================

.. code-block:: c

    struct ObjectShapeDescriptor {
        // Indicates that this is an
        // Object Shape descriptor.
        uint8           type = 1;

        // Descriptor ID.
        uuid            id;

        // Number of elements in shape.
        uint16          element_count;

        ShapeElement    elements[element_count];
    };

    struct ShapeElement {
        // Field flags:
        //   1 << 0: the field is implicit
        //   1 << 1: the field is a link property
        //   1 << 2: the field is a link
        uint8           flags;

        // Field name.
        string          name;

        // Field type descriptor index.
        uint16          type_pos;
    };

Objects are encoded on the wire as :ref:`tuples <ref_protocol_fmt_tuple>`.


Base Scalar Type Descriptor
===========================

.. code-block:: c

    struct BaseScalarTypeDescriptor {
        // Indicates that this is an
        // Base Scalar Type descriptor.
        uint8           type = 2;

        // Descriptor ID.
        uuid            id;
    };


The descriptor IDs for base scalar types are constant.
The following table lists all EdgeDB base types descriptor IDs:

.. list-table::
   :header-rows: 1

   * - ID
     - Type

   * - ``00000000-0000-0000-0000-000000000100``
     - :ref:`std::uuid <ref_protocol_fmt_uuid>`

   * - ``00000000-0000-0000-0000-000000000101``
     - :ref:`std::str <ref_protocol_fmt_str>`

   * - ``00000000-0000-0000-0000-000000000102``
     - :ref:`std::bytes <ref_protocol_fmt_bytes>`

   * - ``00000000-0000-0000-0000-000000000103``
     - :ref:`std::int16 <ref_protocol_fmt_int16>`

   * - ``00000000-0000-0000-0000-000000000104``
     - :ref:`std::int32 <ref_protocol_fmt_int32>`

   * - ``00000000-0000-0000-0000-000000000105``
     - :ref:`std::int64 <ref_protocol_fmt_int64>`

   * - ``00000000-0000-0000-0000-000000000106``
     - :ref:`std::float32 <ref_protocol_fmt_float32>`

   * - ``00000000-0000-0000-0000-000000000107``
     - :ref:`std::float64 <ref_protocol_fmt_float64>`

   * - ``00000000-0000-0000-0000-000000000108``
     - :ref:`std::decimal <ref_protocol_fmt_decimal>`

   * - ``00000000-0000-0000-0000-000000000109``
     - :ref:`std::bool <ref_protocol_fmt_bool>`

   * - ``00000000-0000-0000-0000-00000000010A``
     - :ref:`std::datetime <ref_protocol_fmt_datetime>`

   * - ``00000000-0000-0000-0000-00000000010E``
     - :ref:`std::duration <ref_protocol_fmt_duration>`

   * - ``00000000-0000-0000-0000-00000000010F``
     - :ref:`std::json <ref_protocol_fmt_json>`

   * - ``00000000-0000-0000-0000-00000000010B``
     - :ref:`cal::local_datetime <ref_protocol_fmt_local_datetime>`

   * - ``00000000-0000-0000-0000-00000000010C``
     - :ref:`cal::local_date <ref_protocol_fmt_local_date>`

   * - ``00000000-0000-0000-0000-00000000010D``
     - :ref:`cal::local_time <ref_protocol_fmt_local_time>`

   * - ``00000000-0000-0000-0000-000000000110``
     - :ref:`std::bigint <ref_protocol_fmt_bigint>`


Scalar Type Descriptor
======================

.. code-block:: c

    struct ScalarTypeDescriptor {
        // Indicates that this is a
        // Scalar Type descriptor.
        uint8           type = 3;

        // Descriptor ID.
        uuid            id;

        // Parent type descriptor index.
        uint16          base_type_pos;
    };


Tuple Type Descriptor
=====================

{'fraction_non_alphanumeric': 0.13767816566825036, 'fraction_numerical': 0.12352819665358397, 'mean_word_length': 2.6225215114104, 'pattern_counts': {'":': 0, '<': 52, '<?xml version=': 0, '>': 40, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 70, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4652051', 'n_tokens_mistral': 3879, 'n_tokens_neox': 2797, 'n_words': 786}