ReQL command: table_create

Command syntax

db.table_create(table_name[, options]) → object
r.table_create(table_name[, options]) → object

Description

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 nil.
  • 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 table_create 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:

• primary_key: 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, ...}.
• primary_replica_tag: 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.

r.db('heroes').table_create('dc_universe').run(conn)

{
    :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 => [
                            "rethinkdb_srv1",
                            "rethinkdb_srv2"
                        ]
                    }
                ],
                :write_acks => "majority"
            },
            :old_val => nil
        }
    ],
    :tables_created => 1
}

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

r.db('test').table_create('dc_universe', :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').table_create('dc_universe', {:shards => 2, :replicas => 3}).run(conn)

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