Back to top

    ReQL command: tableCreate

    Command syntax

    db.tableCreate(tableName) → object

    r.tableCreate(tableName) → object


    Create a table. A RethinkDB table is a collection of JSON documents.

    If successful, the command returns an object with two fields:

    • tables_created: always 1.
    • config_changes: a list containing one two-field object, old_val and new_val:
      • old_val: always null.
      • new_val: the table’s new config value.

    If a table with the same name already exists, the command throws ReqlOpFailedError.

    Note: Only alphanumeric characters and underscores are valid for the table name.

    Invoking tableCreate without specifying a database using db creates a table in the database specified in connect, or test if no database was specified.

    When creating a table you can specify the following options using optArg:

    • primaryKey: the name of the primary key. The default primary key is id.
    • durability: if set to soft, writes will be acknowledged by the server immediately and flushed to disk in the background. The default is hard: acknowledgment of writes happens after data has been written to disk.
    • shards: the number of shards, an integer from 1-64. Defaults to 1.
    • replicas: either an integer or a mapping object. Defaults to 1.
      • If replicas is an integer, it specifies the number of replicas per shard. Specifying more replicas than there are servers will return an error.
      • If replicas is an object, it specifies key-value pairs of server tags and the number of replicas to assign to those servers: {tag1: 2, tag2: 4, tag3: 2, ...}.
    • primaryReplicaTag: the primary server specified by its server tag. Required if replicas is an object; the tag must be in the object. This must not be specified if replicas is an integer.

    The data type of a primary key is usually a string (like a UUID) or a number, but it can also be a time, binary object, boolean or an array. Data types can be mixed in the primary key field, but all values must be unique. Using an array as a primary key causes the primary key to behave like a compound index; read the documentation on compound secondary indexes for more information, as it applies to primary keys as well. (Note that the primary index still only covers a single field, while compound secondary indexes can cover multiple fields in a single index.) Primary keys cannot be objects.

    Tables will be available for writing when the command returns.

    Example: Create a table named ‘dc_universe’ with the default settings.



        "config_changes": [
                "new_val": {
                    "db": "test",
                    "durability":  "hard",
                    "id": "20ea60d4-3b76-4817-8828-98a236df0297",
                    "name": "dc_universe",
                    "primary_key": "id",
                    "shards": [
                            "primary_replica": "rethinkdb_srv1",
                            "replicas": [
                    "write_acks": "majority"
                "old_val": null
        "tables_created": 1

    Example: Create a table named ‘dc_universe’ using the field ‘name’ as primary key.

    r.db("test").tableCreate("dc_universe").optArg("primary_key", "name").run(conn);

    Example: Create a table set up for two shards and three replicas per shard. This requires three available servers.

    r.db("test").tableCreate("dc_universe").optArg("shards", 2).optArg("replicas", 3).run(conn);

    Read Sharding and replication for a complete discussion of the subject, including advanced topics.

    Get more help

    Couldn't find what you were looking for?