table_create
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
: always1
. -
config_changes
: a list containing one two-field object,old_val
andnew_val
:-
old_val
: alwaysNone
. -
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, ortest
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 isid
. -
durability
: if set tosoft
, writes will be acknowledged by the server immediately and flushed to disk in the background. The default ishard
: acknowledgment of writes happens after data has been written to disk. -
shards
: the number of shards, an integer from 1-64. Defaults to1
. -
replicas
: either an integer or a mapping object. Defaults to1
.- 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,...}
.
- If
-
primary_replica_tag
: the primary server specified by its server tag. Required ifreplicas
is an object; the tag must be in the object. This must not be specified ifreplicas
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": None } ], "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.
Related commands
Get more help
Couldn't find what you were looking for?
- Ask a question on Stack Overflow
- Chat with us and our community on Slack
- Talk to the team on IRC on #rethinkdb@freenode.net — via Webchat
- Ping @rethinkdb on Twitter
- Post an issue on the documentation issue tracker on GitHub
© RethinkDB contributors
Licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
https://rethinkdb.com/api/python/table_create/