• Contents
  • Getting started
  • Concepts
  • Tutorials
  • Recommendations
  • Managing databases
  • Managing a cluster
  • YQL
  • Working with the YDB CLI
  • Working with the YDB SDK
  • Development
  • Questions and answers
  • Downloads
  • Public talks
  • What's new


The CREATE TABLE call creates a table with the specified data schema and key columns (PRIMARY KEY). It lets you define secondary indexes on the created table.

CREATE TABLE table_name (
    column1 type1,
    column2 type2,
    columnN typeN,
    INDEX index1_name GLOBAL ON ( column ),
    INDEX index2_name GLOBAL ON ( column1, column2, ... ),
    PRIMARY KEY ( column, ... ),
    FAMILY column_family ( family_options, ... )
WITH ( key = value, ... )


For the key and non-key columns, you can only use primitive data types.

All columns are optional by default and can be assigned NULL values. The NOT NULL limit can only be specified for columns that are part of the primary key..
It is mandatory to specify the PRIMARY KEY with a non-empty list of columns. Those columns become part of the key in the listed order.


CREATE TABLE my_table (
    a Uint64 NOT NULL,
    b Bool,
    c Float,
    PRIMARY KEY (b, a)

Secondary indexes

The INDEX construct is used to define a secondary index in a table:

CREATE TABLE table_name ( 
    INDEX <index_name> GLOBAL [SYNC|ASYNC] ON ( <index_columns> ) COVER ( <cover_columns> ),


  • Index_name is the unique name of the index to be used to access data.
  • SYNC/ASYNC indicates synchronous/asynchronous data writes to the index. If not specified, synchronous.
  • Index_columns is a list of comma-separated names of columns in the created table to be used for a search in the index.
  • Cover_columns is a list of comma-separated names of columns in the created table, which will be stored in the index in addition to the search columns, making it possible to fetch additional data without accessing the table for it.


CREATE TABLE my_table (
    a Uint64,
    b Bool,
    c Utf8,
    d Date,
    INDEX idx_d GLOBAL ON (d),
    INDEX idx_ba GLOBAL ASYNC ON (b, a) COVER (c),

Additional parameters

You can also specify a number of YDB-specific parameters for the table. When creating a table using YQL, such parameters are listed in the WITH section:

CREATE TABLE table_name (...)
    key1 = value1,
    key2 = value2,

Here, key is the name of the parameter and value is its value.

For a list of valid parameter names and values, see the YDB table description.

For example, this code will create a table with enabled automatic partitioning by partition size and the preferred size of each partition is 512 MB:

Listing 4

CREATE TABLE my_table (
    id Uint64,
    title Utf8,
    PRIMARY KEY (id)

Column groups

Columns of the same table can be grouped to set the following parameters:

  • DATA: A storage device type for the data in this column group. Acceptable values: ssd, hdd.
  • COMPRESSION: A data compression codec. Acceptable values: off, lz4.

By default, all columns are in the same group named default. If necessary, the parameters of this group can also be redefined.

In the example below, for the created table, the family_large group of columns is added and set for the series_info column, and the parameters for the default group, which is set by default for all other columns, are also redefined.

CREATE TABLE series_with_families (
    series_id Uint64,
    title Utf8,
    series_info Utf8 FAMILY family_large,
    release_date Uint64,
    PRIMARY KEY (series_id),
    FAMILY default (
        DATA = "ssd",
        COMPRESSION = "off"
    FAMILY family_large (
        DATA = "hdd",
        COMPRESSION = "lz4"


Available types of storage devices depend on the YDB cluster configuration.