ReQL command: index_create

Command syntax

table.index_create(index_name[, index_function][, multi=False, geo=False]) → object

Description

Create a new secondary index on a table. Secondary indexes improve the speed of many read queries at the slight cost of increased storage space and decreased write performance. For more information about secondary indexes, read the article “Using secondary indexes in RethinkDB.”

RethinkDB supports different types of secondary indexes:

• Simple indexes based on the value of a single field.
• Compound indexes based on multiple fields.
• Multi indexes based on arrays of values.
• Geospatial indexes based on indexes of geometry objects, created when the geo optional argument is true.
• Indexes based on arbitrary expressions.

The index_function can be an anonymous function or a binary representation obtained from the function field of index_status. The function must be deterministic, and so cannot use a subquery or the r.js command.

If successful, create_index will return an object of the form {"created": 1}. If an index by that name already exists on the table, a ReqlRuntimeError will be thrown.

Note that an index may not be immediately available after creation. If your application needs to use indexes immediately after creation, use the index_wait command to ensure the indexes are ready before use.

Example: Create a simple index based on the field post_id.

r.table('comments').index_create('post_id').run(conn)

Example: Create a simple index based on the nested field author > name.

r.table('comments').index_create('author_name', r.row["author"]["name"]).run(conn)

Example: Create a geospatial index based on the field location.

r.table('places').index_create('location', geo=True).run(conn)

A geospatial index field should contain only geometry objects. It will work with geometry ReQL terms (get_intersecting and get_nearest) as well as index-specific terms (index_status, index_wait, index_drop and index_list). Using terms that rely on non-geometric ordering such as get_all, order_by and between will result in an error.

Example: Create a compound index based on the fields post_id and date.

r.table('comments').index_create('post_and_date', [r.row["post_id"], r.row["date"]]).run(conn)

Example: Create a multi index based on the field authors.

r.table('posts').index_create('authors', multi=True).run(conn)

Example: Create a geospatial multi index based on the field towers.

r.table('networks').index_create('towers', geo=True, multi=True).run(conn)

Example: Create an index based on an arbitrary expression.

r.table('posts').index_create('authors', lambda doc:
    r.branch(
        doc.has_fields("updated_at"),
        doc["updated_at"],
        doc["created_at"]
    )
).run(conn)

Example: Create a new secondary index based on an existing one.

index = r.table('posts').index_status('authors').nth(0)['function'].run(conn)
r.table('new_posts').index_create('authors', index).run(conn)

Example: Rebuild an outdated secondary index on a table.

old_index = r.table('posts').index_status('old_index').nth(0)['function'].run(conn)
r.table('posts').index_create('new_index', old_index).run(conn)
r.table('posts').index_wait('new_index').run(conn)
r.table('posts').index_rename('new_index', 'old_index', overwrite=True).run(conn)