Database

Use create-table to create a table identified by the specified table name.

To create a table identified by the specified table name, use the following syntax:

Before using this function in a Pact module, you must define the table fields using the defschema declaration and the table identifier using the deftable declaration. Creating the table is a separate step that is outside of the Pact module where the schema and identifier are defined.

Use the following argument to specify the table name you want to create using the create-table Pact function.

The create-table function returns a string representing the identifier of the created table.

The following example demonstrates how to use the create-table function to create a table identified by accounts that can be used for storing account information:

The following example illustrates using the create-table function after defining the table schema and table identifier:

Use describe-keyset to retrieve metadata for a specified keyset.

Note: You can only use this function at the top level of your code. The function fails if used within module code.

To get metadata for the specified keyset name, use the following syntax:

Use the following argument to specify the keyset for which to retrieve metadata using the describe-keyset Pact function.

The describe-keyset function returns a guard.

The returned object includes the following properties:

The following example retrieves metadata for a keyset named 'admin-keyset' in the Pact REPL:

Use describe-module to get metadata for a specified module. This function returns an object with fields including name, hash, blessed, code, and keyset.

Note: This function is only allowed in /local in chainweb.

To get metadata for a module, use the following syntax:

Use the following argument to specify the module for the describe-module Pact function.

The describe-module function returns an object with metadata for the specified module.

The following example demonstrates how to use describe-module function to describe a loaded module:

In this example, (describe-module 'm) is used to get metadata for the module named 'm'. The function returns an object providing detailed information about the module.

Use describe-table to get metadata for a specified table. This function returns an object with fields including module, name, and type.

To get metadata for a specified table, use the following syntax:

Use the following argument to specify the table for the describe-table Pact function.

The describe-table function returns an object with metadata for the specified table.

The following example demonstrates use to use the describe-table function in the Pact REPL by loading a module that has a table definition:

The Pact REPL loads the module and displays the has with output similar to the following:

Use fold-db to select rows from a specified table using a predicate query with both a key and a value, and then accumulate the results of the query using a consumer function. The output is sorted by the ordering of keys.

To select rows from a table, apply a predicate, and accumulate the results using a consumer function, use the following syntax:

Use the following arguments to specify the table, predicate, and consumer function for the fold-db Pact function:

The fold-db function returns a list of accumulated results based on the predicate query and the consumer function.

The following example demonstrates how to use the fold-db function:

In this example:

The fold-db function is then used to select rows from the people table using the predicate qry and accumulate the results using the consumer function f. The result is a list of accumulated results based on the selected rows and the specified consumer function. The fold-db function is useful for iterating over rows in a table and performing operations in Pact contracts.

Use insert to write an entry in a specified table for a given key of object data. This operation fails if data already exists for the specified key.

To insert data into a table for a specified key, use the following syntax:

Use the following arguments to specify the table, key, and object data you want to insert using the insert Pact function.

The insert function returns a string indicating the success or an exception on failure of the operation.

The following example demonstrates how to use the insert function to insert information into the accounts table for the account specified using the id for the account:

The following example illustrates a more complete flow from defining the table schema to inserting values into the table:

Use keylog to return updates to a specified table for a given key in transactions at or after a specified transaction identifier (txid), in a list of objects indexed by transaction identifiers.

To retrieve updates to a table for a specific key in transactions at or after a specified txid value, use the following syntax:

Use the following arguments to specify the table, key, and transaction identifier for which you want to retrieve updates using the keylog Pact function.

The keylog function returns a list of objects containing updates to the specified table for the given key, indexed by transaction identifier.

The following example demonstrates how to use the keylog function to retrieve updates for the accounts table for the key "Alice", starting from transaction identifier 123485945:

Use keys to retrieve all the keys in a specified table.

To retrieve all of the keys for a specified table, use the following syntax:

Use the following argument to specify the table from which to retrieve keys using the keys Pact function.

The keys function returns an array of strings, where each string represents a key in the specified table.

The following example demonstrates defining a table schema for an accounts table that stores information about bank accounts, including the balance and owner of each account:

You can then retrieve all of the the keys from the accounts table using the keys function:

Use list-modules to get all of the modules deployed on a particular chain.

Note: This function is only allowed in /local in chainweb.

To list all modules in /local, use

None

The list-modules function returns a list of all module names (including their namespace) stored on-chain

The following example deploys a simple module in the repl, then calls list-modules.

Use read to retrieve a row from a specified table by its key. You can optionally specify a subset of columns to return.

To read an entire row from a table, use the following syntax:

To read specific columns from a row in a table, use the following syntax:

Use the following arguments to specify the table, key, and optional columns when using the read Pact function.

The read function returns an object representing the requested row or columns from the specified table.

he following example demonstrates defining a table schema for an accounts table that stores information about bank accounts, including the balance, currency, and owner of each account:

You can then use the read function to read a row from the accounts table by its key id and retrieve only the balance and currency columns:

Use select to retrieve full rows or specified columns from a table by applying a where clause to each row to determine whether to include the row or column in the selection.

To select full rows from a table based on a where clause, use the following syntax:

To select specific columns from a table based on a where clause, use the following syntax:

Use the following arguments to specify the table, columns, and where clause for selecting rows using the select Pact function.

The select function returns a list of objects representing the selected rows from the table that satisfy the where condition.

The following example demonstrates how to use the select function to select the columns 'firstName and 'lastName from the people table where the name is equal to "Fatima":

The following example demonstrates how to select all columns from the people table where the age is less than 30:

Ue txids to return all of the transaction identifiers greater than or equal to a specified txid in a given table.

To retrieve all transaction identifier values greater than or equal to a specified txid in a table, use the following syntax:

Use the following arguments to specify the table and transaction identifier for retrieval using the txids Pact function.

The txids function returns a list of transaction identifiers greater than or equal to the specified txid in the specified table.

The following example demonstrates how to use the txids function to retrieve all transaction identifier values greater than or equal to 123849535 in the accounts table:

Use txlog to return all updates made to a specified table in a particular transaction identified by its transaction identifier.

To retrieve all updates made to the specified table in a specific transaction identifier, use the following syntax:

Use the following arguments to specify the table and transaction identifier for retrieval using the txlog Pact function.

The txlog function returns a list of objects representing all updates made to the specified table in the transaction identified by the txid provided.

The following example demonstrates how to use the txlog function to retrieve all updates made to the accounts table in the transaction with the 123485945 transaction identifier:

Use update to write an entry in the specified table for a given key with the data provided in the object column. It fails if data does not exist for the specified key.

To update an entry in the specified table for a specific key with the provided object column data, use the following syntax:

Use the following arguments to specify the table, key, and object data for updating a table using the update Pact function.

The update function returns a string indicating the success of the update operation.

The following example demonstrates how to use the update function to update an entry in the accounts table for the specified key with the provided object column data:

This example illustrates how to use the update function to modify an entry in a table with new data in Pact, ensuring that the operation fails if data does not exist for the specified key.

Use with-default-read to read a row from a specified table for a given key and bind columns according to provided bindings. If the row is not found, the function reads columns from a default object with matching key names.

To read a row from a table with default values and bind columns according to the provided binding, use the following syntax:

Use the following arguments to specify the table, key, defaults, bindings, and body for execution using the with-default-read Pact special form.

The with-default-read is a special form that returns the result of executing the provided body statements.

The following example demonstrates how to use the with-default-read function to read a row from the accounts table for the specified key, using default values if the row is not found, and binds the balance and currency columns for further processing:

This example illustrates reading the accounts table with the row key of id and setting default values of 0 and USD for the balance and currency columns if the row isn't found to format a default message using the format function.

Use with-read to read a row from a specified table for a given key and bind columns according to provided bindings over subsequent body statements.

To read a row from a table and bind columns according to provided bindings, use the following syntax:

Use the following arguments to specify the table, key, bindings, and body for execution using the with-read Pact special form.

The with-read is a special form returns the result of executing the provided body statements.

The following example demonstrates how to use the with-read function to read a row from the accounts table for the specified key and bind the balance and currency columns for further processing:

Use write to write the specified {column:value} object in the specified table for a given key row. The write function is similar to the insert and update functions, except that:

In both of these cases, the write function can succeed and update the table without failing.

To write an entry in a specified table for a specific key with the provided object, use the following syntax:

Use the following arguments to specify the table, key, and object data for writing using the write Pact function.

The write function returns a string indicating the success of the write operation.

The following example demonstrates how to use the write function to write an entry in the accounts table for the specified key with the provided object column data:

This example illustrates inserting data into the balance column in the accounts table using the id as the row key.