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_name	table
capi_name capi_name	payer
capi_name capi_name uint64_t	id
capi_name capi_name uint64_t const void *	data
capi_name capi_name uint64_t const void uint32_t	len
uint64_t *	primary
uint64_t	scope
capi_name capi_name uint64_t const uint64_t *	secondary
capi_name capi_name uint64_t const uint128_t uint32_t	data_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:

Primary Table
- 64-bit integer key
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

Database C API

Functions​

Attributes​

Detailed Description​

Supported Table Types

Functions Documentation​

function attribute​

Attributes Documentation​

variable table​

variable payer​

variable id​

variable data​

variable len​

variable primary​

variable scope​

variable secondary​

variable data_len​

Functions

Attributes

Detailed Description

Functions Documentation

function attribute

Attributes Documentation

variable table

variable payer

variable id

variable data

variable len

variable primary

variable scope

variable secondary

variable data_len