Skip to main content

Primary Index

Overview​

This guide provides instructions to define a primary index for a multi-index table.

Procedure​

Complete the following steps to define a primary index for the multi-index table datatable.

1. Preparation And Initialization​

Include the inery.hpp header and use the using directive to access the inery namespace.

#include <inery/inery.hpp>
using namespace inery;

2. Define The Table Data Structure​

Define the data structure for the multi-index table.

  struct [[inery::table]] data_structure {
  };

Add the data structure data members. Each data member corresponds to a field of the multi-index table. A primary key is required when defining a multi-index table structure, therefore you need to know which is the multi-index table field that is the primary key for your multi-index table. The corresponding data member for the primary key field must store unique values. In this case it is the test_primary data member of type inery::name.

  // the data structure which defines each row of the table
  struct [[inery::table]] data_structure {
+    // this data member stores a name for each row of the multi-index table
+    name test_primary;
+    // additional data stored in table row, e.g. an uint64_t type data
+    uint64_t datum;
  };

3. Define The Primary Index​

Add the definition of the primary index for the multi-index table. The primary index type must be uint64_t, it must be unique and must be named primary_key(), otherwise the compiler (inery-cpp) will generate an error saying it can not find the field to use as the primary key:

  // the data structure which defines each row of the table
  struct [[inery::table]] data_structure {
    // this data member stores a name for each row of the multi-index table
    name test_primary;
    // additional data stored in table row
    uint64_t datum;
+    // mandatory definition for primary key getter
+    uint64_t primary_key( ) const { return test_primary.value; }
  };

Secondary indexes may be defined which are not unique. There can be up to 16 secondary indexes. Secondary indices support the following types:

  • uint64_t
  • uint128_t
  • uint256_t
  • double
  • long double

4. Using A Multi-Index Type Alias​

For ease of use, define a type alias data_structure_t based on the inery::multi_index template type, parametarized with a random name "datatable" and the data_structure data structure. The names must adhere to INERY account name restrictions.

  // the data structure which defines each row of the table
  struct [[inery::table]] data_structure {
    // this data member stores a name for each row of the multi-index table
    name test_primary;
    // additional data stored in table row
    uint64_t datum;
    // mandatory definition for primary key getter
    uint64_t primary_key( ) const { return test_primary.value; }
  };
  
+  typedef inery::multi_index<"datatable"_n, data_structure> data_structure_t;

5. Instantiate The Multi-Index Table​

Declare the datatable multi-index table as a data member of type data_structure_t.

  // the data structure which defines each row of the table
  struct [[inery::table]] data_structure {
    // this data member stores a name for each row of the multi-index table
    name test_primary;
    // additional data stored in table row
    uint64_t datum;
    // mandatory definition for primary key getter
    uint64_t primary_key( ) const { return test_primary.value; }
  };
  
  typedef inery::multi_index<"datatable"_n, data_structure> data_structure_t;
+  data_structure_t datatable;

Now you have instantiated a multi-index table, and assigned to datatable variable, which has a primary index defined for its test_primary data member.

Summary​

In conclusion, the above instructions show how to define a primary index for a multi-index table.

Last updated on