Skip to main content

Database C API

Defines C APIs for interfacing with the database. More...

Functions​

Name
attribute((eosio_wasm_import) )
Store a record in a primary 64-bit integer index table.

Attributes​

Name
capi_nametable
capi_namecapi_namepayer
capi_namecapi_name uint64_tid
capi_namecapi_name uint64_t const void *data
capi_namecapi_name uint64_t const void uint32_tlen
uint64_t *primary
uint64_tscope
capi_namecapi_name uint64_t const uint64_t *secondary
capi_namecapi_name uint64_t const uint128_t uint32_tdata_len

Detailed Description​

Defines C APIs for interfacing with the database.

Database C API provides low level interface to EOSIO database.

Supported Table Types

Following are the table types supported by the C API:

  1. Primary Table
    • 64-bit integer key
  2. Secondary Index Table
    • 64-bit integer key
    • 128-bit integer key
    • 256-bit integer key
    • double key
    • long double key

Functions Documentation​

function attribute​

__attribute__(
    (eosio_wasm_import) 
)

Store a record in a primary 64-bit integer index table.

Parameters:

  • scope - The scope where the table resides (implied to be within the code of the current receiver)
  • table - The table name
  • payer - The account that pays for the storage costs
  • id - ID of the entry
  • data - Record to store
  • len - Size of data
  • iterator - Iterator to the table row containing the record to update
  • payer - The account that pays for the storage costs (use 0 to continue using current payer)
  • data - New updated record
  • len - Size of data
  • iterator - Iterator to the table row to remove
  • iterator - The iterator to the table row containing the record to retrieve
  • data - Pointer to the buffer which will be filled with the retrieved record
  • len - Size of the buffer
  • iterator - The iterator to the referenced table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the next table row
  • iterator - The iterator to the referenced table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the previous table row
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • id - The primary key of the table row to look up
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • id - The primary key used to determine the lowerbound
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • id - The primary key used to determine the upperbound
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • scope - The scope where the table resides (implied to be within the code of the current receiver)
  • table - The table name
  • payer - The account that pays for the storage costs
  • id - The primary key to which to associate the secondary key
  • secondary - Pointer to the secondary key
  • iterator - The iterator to the table row containing the secondary key association to update
  • payer - The account that pays for the storage costs (use 0 to continue using current payer)
  • secondary - Pointer to the new secondary key that will replace the existing one of the association
  • iterator - Iterator to the table row to remove
  • iterator - The iterator to the referenced table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the next table row
  • iterator - The iterator to the referenced table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the previous table row
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to a uint64_t variable which will have its value set to the secondary key of the found table row
  • primary - The primary key of the table row to look up
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to secondary key used to lookup the table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the found table row
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to secondary key first used to determine the lowerbound and which is then replaced with the secondary key of the found table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the found table row
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the found table row
  • scope - The scope where the table resides (implied to be within the code of the current receiver)
  • table - The table name
  • payer - The account that pays for the storage costs
  • id - The primary key to which to associate the secondary key
  • secondary - Pointer to the secondary key
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to a uint128_t variable which will have its value set to the secondary key of the found table row
  • primary - The primary key of the table row to look up
  • scope - The scope where the table resides (implied to be within the code of the current receiver)
  • table - The table name
  • payer - The account that pays for the storage costs
  • id - The primary key to which to associate the secondary key
  • data - Pointer to the secondary key data stored as an array of 2 uint128_t integers
  • data_len - Must be set to 2
  • iterator - The iterator to the table row containing the secondary key association to update
  • payer - The account that pays for the storage costs (use 0 to continue using current payer)
  • data - Pointer to the new secondary key data (which is stored as an array of 2 uint128_t integers) that will replace the existing one of the association
  • data_len - Must be set to 2
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • data - Pointer to the an array of 2 uint128_t integers which will act as the buffer to hold the retrieved secondary key of the found table row
  • data_len - Must be set to 2
  • primary - The primary key of the table row to look up
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • data - Pointer to the secondary key data (which is stored as an array of 2 uint128_t integers) used to lookup the table row
  • data_len - Must be set to 2
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the found table row
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • data - Pointer to the secondary key data (which is stored as an array of 2 uint128_t integers) first used to determine the lowerbound and which is then replaced with the secondary key of the found table row
  • data_len - Must be set to 2
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the found table row
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • data - Pointer to the secondary key data (which is stored as an array of 2 uint128_t integers) first used to determine the upperbound and which is then replaced with the secondary key of the found table row
  • data_len - Must be set to 2
  • primary - Pointer to a uint64_t variable which will have its value set to the primary key of the found table row
  • scope - The scope where the table resides (implied to be within the code of the current receiver)
  • table - The table name
  • payer - The account that pays for the storage costs
  • id - The primary key to which to associate the secondary key
  • secondary - Pointer to the secondary key
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to a double variable which will have its value set to the secondary key of the found table row
  • primary - The primary key of the table row to look up
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to secondary key used to lookup the table row
  • primary - Pointer to a double variable which will have its value set to the primary key of the found table row
  • scope - The scope where the table resides (implied to be within the code of the current receiver)
  • table - The table name
  • payer - The account that pays for the storage costs
  • id - The primary key to which to associate the secondary key
  • secondary - Pointer to the secondary key
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to a long double variable which will have its value set to the secondary key of the found table row
  • primary - The primary key of the table row to look up
  • code - The name of the owner of the table
  • scope - The scope where the table resides
  • table - The table name
  • secondary - Pointer to secondary key used to lookup the table row
  • primary - Pointer to a long double variable which will have its value set to the primary key of the found table row

Return:

  • iterator to the newly created table row
  • size of the data copied into the buffer if len > 0, or size of the retrieved record if len == 0.
  • iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table)
  • iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table)
  • iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found
  • iterator to the found table row or the end iterator of the table if the table row could not be found
  • iterator to the found table row or the end iterator of the table if the table row could not be found
  • end iterator of the table
  • iterator to the newly created table row
  • iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table)
  • iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table)
  • iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found
  • iterator to the first table row with a secondary key equal to *secondary or the end iterator of the table if the table row could not be found
  • iterator to the found table row or the end iterator of the table if the table row could not be found
  • iterator to the found table row or the end iterator of the table if the table row could not be found
  • iterator to the newly created table row
  • iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found
  • iterator to the newly created table row
  • iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found
  • iterator to the first table row with a secondary key equal to the specified secondary key or the end iterator of the table if the table row could not be found
  • iterator to the found table row or the end iterator of the table if the table row could not be found
  • iterator to the found table row or the end iterator of the table if the table row could not be found
  • iterator to the newly created table row
  • iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found
  • iterator to the first table row with a secondary key equal to *secondary or the end iterator of the table if the table row could not be found
  • iterator to the newly created table row
  • iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found
  • iterator to the first table row with a secondary key equal to *secondary or the end iterator of the table if the table row could not be found

Precondition:

  • data is a valid pointer to a range of memory at least len bytes long
  • *((uint64_t*)data) stores the primary key
  • data is a valid pointer to a range of memory at least len bytes long
  • *((uint64_t*)data) stores the primary key
  • iterator points to an existing table row in the table
  • iterator points to an existing table row in the table
  • iterator points to an existing table row in the table
  • data is a valid pointer to a range of memory at least len bytes long
  • iterator points to an existing table row in the table
  • iterator points to an existing table row in the table or it is the end iterator of the table
  • iterator points to an existing table row in the table
  • iterator points to an existing table row in the table
  • iterator points to an existing table row in the table
  • iterator points to an existing table row in the table or it is the end iterator of the table
  • iterator points to an existing table row in the table

Postcondition:

  • a new entry is created in the table
  • the record contained in the table row pointed to by iterator is replaced with the new updated record
  • the table row pointed to by iterator is removed and the associated storage costs are refunded to the payer
  • data will be filled with the retrieved record (truncated to the first len bytes if necessary)
  • *primary will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise *primary will be left untouched
  • *primary will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise *primary will be left untouched
  • new secondary key association between primary key id and secondary key *secondary is created in the secondary 64-bit integer index table
  • the secondary key of the table row pointed to by iterator is replaced by *secondary
  • the table row pointed to by iterator is removed and the associated storage costs are refunded to the payer
  • *primary will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise *primary will be left untouched
  • *primary will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise *primary will be left untouched
  • If and only if the table row is found, *secondary will be replaced with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • If and only if the table row is found, *secondary will be replaced with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • If and only if the table row is found, *secondary will be replaced with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • new secondary key association between primary key id and secondary key *secondary is created in the secondary 128-bit integer index table
  • If and only if the table row is found, *secondary will be replaced with the secondary key of the found table row
  • new secondary key association between primary key id and the specified secondary key is created in the secondary 256-bit index table
  • the secondary key of the table row pointed to by iterator is replaced by the specified secondary key
  • If and only if the table row is found, the buffer pointed to by data will be filled with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • If and only if the table row is found, the buffer pointed to by data will be filled with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • If and only if the table row is found, the buffer pointed to by data will be filled with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • new secondary key association between primary key id and secondary key *secondary is created in the secondary double-precision floating-point index table
  • If and only if the table row is found, *secondary will be replaced with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row
  • new secondary key association between primary key id and secondary key *secondary is created in the secondary quadruple-precision floating-point index table
  • If and only if the table row is found, *secondary will be replaced with the secondary key of the found table row
  • If and only if the table row is found, *primary will be replaced with the primary key of the found table row

Remark: This function does not allow changing the primary key of a table row. The serialized data that is stored in the table row of a primary table may include a primary key and that primary key value could be changed by the contract calling the db_update_i64 intrinsic; but that does not change the actual primary key of the table row.

Get an end iterator representing just-past-the-end of the last table row of a secondary quadruple-precision floating-point index table.

Find the table row in a secondary quadruple-precision floating-point index table that matches the upperbound condition for a given secondary key.

Find the table row in a secondary quadruple-precision floating-point index table that matches the lowerbound condition for a given secondary key.

Find a table row in a secondary quadruple-precision floating-point index table by secondary key.

Find a table row in a secondary quadruple-precision floating-point index table by primary key.

Find the table row preceding the referenced table row in a secondary quadruple-precision floating-point index table.

Find the table row following the referenced table row in a secondary quadruple-precision floating-point index table.

Remove a table row from a secondary quadruple-precision floating-point index table.

Update an association for a quadruple-precision floating-point secondary key to a primary key in a secondary quadruple-precision floating-point index table.

Store an association of a quadruple-precision floating-point secondary key to a primary key in a secondary quadruple-precision floating-point index table.

Get an end iterator representing just-past-the-end of the last table row of a secondary double-precision floating-point index table.

Find the table row in a secondary double-precision floating-point index table that matches the upperbound condition for a given secondary key.

Find the table row in a secondary double-precision floating-point index table that matches the lowerbound condition for a given secondary key.

Find a table row in a secondary double-precision floating-point index table by secondary key.

Find a table row in a secondary double-precision floating-point index table by primary key.

Find the table row preceding the referenced table row in a secondary double-precision floating-point index table.

Find the table row following the referenced table row in a secondary double-precision floating-point index table.

Remove a table row from a secondary double-precision floating-point index table.

Update an association for a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point index table.

Store an association of a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point index table.

Get an end iterator representing just-past-the-end of the last table row of a secondary 256-bit index table.

Find the table row in a secondary 256-bit index table that matches the upperbound condition for a given secondary key.

Find the table row in a secondary 256-bit index table that matches the lowerbound condition for a given secondary key.

Find a table row in a secondary 256-bit index table by secondary key.

Find the table row preceding the referenced table row in a secondary 256-bit index table.

Find the table row following the referenced table row in a secondary 256-bit index table.

Remove a table row from a secondary 256-bit index table.

Update an association for a 256-bit secondary key to a primary key in a secondary 256-bit index table.

Store an association of a 256-bit secondary key to a primary key in a secondary 256-bit index table.

Get an end iterator representing just-past-the-end of the last table row of a secondary 128-bit integer index table.

Find the table row in a secondary 128-bit integer index table that matches the upperbound condition for a given secondary key.

Find the table row in a secondary 128-bit integer index table that matches the lowerbound condition for a given secondary key.

Find a table row in a secondary 128-bit integer index table by secondary key.

Find a table row in a secondary 128-bit integer index table by primary key.

Find the table row preceding the referenced table row in a secondary 128-bit integer index table.

Find the table row following the referenced table row in a secondary 128-bit integer index table.

Remove a table row from a secondary 128-bit integer index table.

Update an association for a 128-bit integer secondary key to a primary key in a secondary 128-bit integer index table.

Store an association of a 128-bit integer secondary key to a primary key in a secondary 128-bit integer index table.

Get an end iterator representing just-past-the-end of the last table row of a secondary 64-bit integer index table.

Find the table row in a secondary 64-bit integer index table that matches the upperbound condition for a given secondary key.

Find the table row in a secondary 64-bit integer index table that matches the lowerbound condition for a given secondary key.

Find a table row in a secondary 64-bit integer index table by secondary key.

Find a table row in a secondary 64-bit integer index table by primary key.

Find the table row preceding the referenced table row in a secondary 64-bit integer index table.

Find the table row following the referenced table row in a secondary 64-bit integer index table.

Remove a table row from a secondary 64-bit integer index table.

Update an association for a 64-bit integer secondary key to a primary key in a secondary 64-bit integer index table.

Store an association of a 64-bit integer secondary key to a primary key in a secondary 64-bit integer index table.

Get an iterator representing just-past-the-end of the last table row of a primary 64-bit integer index table.

Find the table row in a primary 64-bit integer index table that matches the upperbound condition for a given primary key.

Find the table row in a primary 64-bit integer index table that matches the lowerbound condition for a given primary key.

Find a table row in a primary 64-bit integer index table by primary key.

Find the table row preceding the referenced table row in a primary 64-bit integer index table.

Find the table row following the referenced table row in a primary 64-bit integer index table.

Get a record in a primary 64-bit integer index table.

Remove a record from a primary 64-bit integer index table.

Update a record in a primary 64-bit integer index table.

Example:

int32_t itr = db_find_i64(receiver, receiver, table1, "alice"_n);
eosio_assert(itr >= 0, "Alice cannot be removed since she was already not found in the table");
db_remove_i64(itr);

Example:

char value[50];
auto len = db_get_i64(itr, value, 0);
eosio_assert(len <= 50, "buffer to small to store retrieved record");
db_get_i64(itr, value, len);

Example:

int32_t charlie_itr = db_find_i64(receiver, receiver, table1, "charlie"_n);
// expect nothing after charlie
uint64_t prim = 0
int32_t  end_itr = db_next_i64(charlie_itr, &prim);
eosio_assert(end_itr < -1, "Charlie was not the last entry in the table");

Example:

uint64_t prim = 0;
int32_t  itr_prev = db_previous_i64(itr, &prim);

Example:

int itr = db_find_i64(receiver, receiver, table1, "charlie"_n);

The table row that matches the lowerbound condition is the first table row in the table with the lowest primary key that is >= the given key The table row that matches the upperbound condition is the first table row in the table with the lowest primary key that is > the given key The table row that matches the lowerbound condition is the first table row in the table with the lowest secondary key that is >= the given key The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key The table row that matches the lowerbound condition is the first table row in the table with the lowest secondary key that is >= the given key (uses lexicographical ordering on the 256-bit keys) The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key (uses lexicographical ordering on the 256-bit keys)

Attributes Documentation​

variable table​

capi_name table;

variable payer​

capi_namecapi_name payer;

variable id​

capi_namecapi_name uint64_t id;

variable data​

capi_namecapi_name uint64_t const void * data;

variable len​

capi_namecapi_name uint64_t const void uint32_t len;

variable primary​

uint64_t * primary;

variable scope​

uint64_t scope;

variable secondary​

capi_namecapi_name uint64_t const uint64_t * secondary;

variable data_len​

capi_namecapi_name uint64_t const uint128_t uint32_t data_len;

Updated on 2022-12-05 at 15:38:07 +0000