<para xmlns="http://docbook.org/ns/docbook" version="5.0"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xml:id="space">
<bridgehead>Space settings explained</bridgehead>
Space is a composite parameter, that is, it has properties.
<programlisting language="cpp">
/*
 * Each tuple consists of fields. Three field types are
 * supported.
 */

enum { STR, NUM, NUM64 } field_type;

/*
 * Tarantool is interested in field types only inasmuch as
 * it needs to build indexes on fields. An index
 * can cover one or more fields.
 */

struct index_field_t {
  unsigned int fieldno;
  enum field_type type;
};

/*
 * HASH and TREE and BITSET index types are supported.
 */

enum { HASH, TREE, BITSET } index_type;

struct index_t {
  index_field_t key_field[];
  enum index_type type;
  /* Secondary index may be non-unique */
  bool unique;
};

struct space_t
{
  /* A space can be quickly disabled and re-enabled at run time. */
  bool enabled;
  /*
   * If cardinality is given, each tuple in the space must have exactly
   * this many fields.
   */
  unsigned int cardinality;
  /* estimated_rows is only used for HASH indexes, to preallocate memory. */
  unsigned int estimated_rows;
  struct index_t index[];
};
</programlisting>
The way a space is defined in a configuration file is similar to how
one would initialize a C structure in a program. For example,
a minimal storage configuration looks like the following:
<programlisting language="c">
space[0].enabled = 1
space[0].index[0].type = HASH
space[0].index[0].unique = 1
space[0].index[0].key_field[0].fieldno = 0
space[0].index[0].key_field[0].type = NUM64
</programlisting>
The parameters listed above are mandatory. Other space
properties are set in the same way.
An alternative syntax, mainly useful when defining large spaces, exists:
<programlisting language="c">
space[0] = {
    enabled = 1,
    index = [
        {
            type = HASH,
            key_field = [
                {
                    fieldno = 0,
                    type = NUM64
                }
            ]
        }
    ]
}
</programlisting>
When defining a space,
please be aware of these restrictions:
<itemizedlist>
  <listitem><simpara>at least one space must be
    configured,</simpara></listitem>
  <listitem><simpara>each configured space needs at least one
    unique index,
  </simpara></listitem>
  <listitem><simpara>"unique" property doesn't have a default, and
    must be set explicitly,
  </simpara></listitem>
  <listitem><simpara>space configuration can not be changed
    dynamically, currently you need to restart the server even to
    disable or enable a space,
  </simpara></listitem>
  <listitem><simpara>HASH indexes can not be non-unique.
  </simpara></listitem>
</itemizedlist>
</para>
<!--
vim: tw=66 syntax=docbk
vim: spell spelllang=en_us
-->
