Database

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

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

(create-table TABLE)

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

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

The following example demonstrates the create-table function:

In this example, (create-table accounts) is used to create a table identified by accounts. This creates a new table in Pact that can be used for storing data, and the function returns a string representing the identifier of the created table.

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

Note: This function can only be used at the top level of your code. It will fail if used within module code.

(describe-keyset keyset)

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-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 TABLE, use the following syntax:

(describe-table TABLE)

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 the describe-table function:

In this example, (describe-table accounts) is used to get metadata for the table named 't'. The function returns an object with fields such as module, name and type, providing detailed information about the table.

Use fold-db to select rows from a table TABLE using a predicate QRY with both key and 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:

(fold-db TABLE QRY CONSUMER)

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 QRY and the consumer function CONSUMER.

The following example demonstrates 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:

(insert table key object)

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 the use of insert to insert data into the accounts table:

In this example, data with the specified object is inserted into the accounts table for the given id key. If successful, it returns a string indicating success; otherwise, it fails if data already exists for the specified key.

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

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

(keylog table key txid)

Use the following arguments to specify the table, key, and transaction ID 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 ID.

The following example demonstrates the use of keylog in the Pact REPL to retrieve updates for the "accounts" table, specifically for the key "Alice", starting from transaction ID 123485945:

In this example, updates to the "accounts" table for the key "Alice", starting from transaction ID 123485945, are returned as a list of objects indexed by transaction ID.

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

(keys table)

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.

Suppose we have a table named accounts with the following schema:

The accounts table stores information about bank accounts, including the balance and owner of each account.

The following example retrieves all the keys from the accounts table:

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:

(read table key)

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

(read table key columns)

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.

Suppose we have a table named accounts with the following schema:

The accounts table stores information about bank accounts, including the balance, currency (ccy), and owner of each account.

The following example reads a row from the accounts table by its key id and retrieves only the balance and ccy columns:

The select function retrieves full rows or specified columns from a table by applying a WHERE clause to each row to determine inclusion.

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

(select TABLE WHERE)

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

(select TABLE COLUMNS WHERE)

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 examples demonstrate the usage of the select function within a Pact script.

To select the columns 'firstName and 'lastName from the people table where the name is equal to "Fatima":

To select all columns from the people table where the age is less than 30:

These examples illustrate how to use the select function to retrieve rows or columns from a table based on specified conditions using a WHERE clause in Pact.

The txids function returns all transaction IDs (txids) greater than or equal to a specified txid in a given table.

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

(txids TABLE TXID)

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

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

The following example demonstrates the usage of the txids function within a Pact script. It retrieves all txid values greater than or equal to 123849535 in the accounts table:

This example illustrates how to use the txids function to retrieve transaction IDs (txids) from a table in Pact based on a specified txid.

The txlog function returns all updates made to a specified table in a particular transaction identified by its transaction ID (TXID).

To retrieve all updates made to TABLE in a specific transaction TXID, use the following syntax:

(txlog TABLE TXID)

Use the following arguments to specify the table and transaction ID (TXID) 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 provided TXID.

The following example demonstrates the usage of the txlog function within a Pact script. It retrieves all updates made to the accounts table in the transaction with the TXID 123485945:

This example illustrates how to use the txlog function to obtain the updates performed on a specific table in a given transaction in Pact.

The update function writes 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 TABLE for a specific KEY with the provided OBJECT column data, use the following syntax:

(update table key object)

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

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

The following example demonstrates the usage of the update function within a Pact script. It updates 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.

The with-default-read special form is used 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, it reads columns from defaults, an object with matching key names.

To read a row from a TABLE with DEFAULTs values and bind columns according to provided BINDINGS, use the following syntax:

(with-default-read TABLE KEY DEFAULTS BINDINGS)

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 special form returns the result of executing the provided body statements.

The following example demonstrates the usage of the with-default-read special form within a Pact script. It reads a row from the accounts table for the specified key, using default values if the row is not found, and binds the 'balance' and 'ccy' columns for further processing:

This example illustrates how to use the with-default-read special form to handle missing rows from a table and provide default values for further operations in Pact, ensuring consistent behavior when accessing data.

The with-read special form is used 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:

(with-read TABLE KEY BINDINGS)

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

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

The following example demonstrates the usage of the with-read special form within a Pact script. It reads a row from the accounts table for the specified key and binds the 'balance' and 'ccy' columns for further processing:

This example illustrates how to use the with-read special form to read data from a table and bind specific columns for further operations in Pact, facilitating efficient data retrieval and processing.

The write function writes an entry in the specified table for a given key with the data provided in the object column.

To write an entry in a TABLE for a specific KEY with the provided OBJECT column data, use the following syntax:

(write TABLE KEY OBJECT)

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 the usage of the write function within a Pact script. It writes an entry in the accounts table for the specified key with the provided object column data:

This example illustrates how to use the write function to insert data into a table in Pact, enabling the storage of structured information for later retrieval and manipulation.