Skip to main content
Last updated

Database

create-table

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

Basic syntax

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

(create-table TABLE)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table to create.

Return values

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

Example

The following example demonstrates the create-table function:

pact
(create-table accounts)
pact
(create-table accounts)

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.

describe-keyset

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.

Basic syntax

(describe-keyset keyset)

Arguments

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

ArgumentTypeDescription
keysetstringSpecifies the name of the keyset for which to retrieve metadata.

Return values

The describe-keyset function returns a guard.

The returned object includes the following properties:

  • pred: The predicate function associated with the keyset.
  • keys: An array of public keys associated with the keyset.

Examples

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

lisp
pact> (describe-keyset 'admin-keyset){  "pred": "keys-all",  "keys": [    "ba54b224d1924dd98403f5c751abdd10de6cd81b0121800bf7bdbdcfaec7388d",    "8cc94f8a4b43f4d9e3f8c5dca3966ea000f13ecbd79abc01bc7c00faacd06a5e"  ]}
lisp
pact> (describe-keyset 'admin-keyset){  "pred": "keys-all",  "keys": [    "ba54b224d1924dd98403f5c751abdd10de6cd81b0121800bf7bdbdcfaec7388d",    "8cc94f8a4b43f4d9e3f8c5dca3966ea000f13ecbd79abc01bc7c00faacd06a5e"  ]}

describe-table

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

Basic syntax

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

(describe-table TABLE)

Arguments

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

ArgumentTypeDescription
tabletable:<{row}>Specifies the table to describe.

Return values

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

Examples

The following example demonstrates the describe-table function:

pact
pact>(module m G (defcap G () true) (defschema s i:integer) (deftable t:{s}))Loaded module m, hash UAnq05ArrOYCFbeJDjCLpWecBq5bS5I0WA6Mj0O041opact>(describe-table m.t){"module":"m", "name":"t", "type":"table{m.s}"}
pact
pact>(module m G (defcap G () true) (defschema s i:integer) (deftable t:{s}))Loaded module m, hash UAnq05ArrOYCFbeJDjCLpWecBq5bS5I0WA6Mj0O041opact>(describe-table m.t){"module":"m", "name":"t", "type":"table{m.s}"}

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.

fold-db

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.

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table from which to select rows.
QRYa:string b:object:<{row}> -> boolSpecifies the predicate function to apply to each row.
CONSUMERa:string b:object:<{row}> -> <b> -> [<b>]Specifies the consumer function to accumulate results.

Return values

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

Examples

The following example demonstrates the fold-db function:

pact
(let  ((qry (lambda (k obj) true)) ;; Select all rows   (f (lambda (x) [(at 'firstName x), (at 'b x)])) ;; Example consumer function  )  (fold-db people qry f))
pact
(let  ((qry (lambda (k obj) true)) ;; Select all rows   (f (lambda (x) [(at 'firstName x), (at 'b x)])) ;; Example consumer function  )  (fold-db people qry f))

In this example:

  • (qry (lambda (k obj) true)) is a predicate that selects all rows.
  • (f (lambda (x) [(at 'firstName x), (at 'b x)])) is a consumer function that selects the 'firstName' and 'b' fields from each row.

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.

insert

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.

Basic syntax

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

(insert table key object)

Arguments

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

ArgumentTypeDescription
tabletable<{row}>Specifies the table where the entry will be written.
keystringSpecifies the key for which the data will be inserted.
objectobject<{row}>Specifies the object data to be inserted for the specified key.

Return value

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

Examples

The following example demonstrates the use of insert to insert data into the accounts table:

pact
(insert accounts id { "balance": 0.0, "note": "Created account." })
pact
(insert accounts id { "balance": 0.0, "note": "Created account." })

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.

keylog

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.

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
tabletable<{row}>Specifies the table from which updates will be retrieved.
keystringSpecifies the key for which updates will be retrieved.
txidintegerSpecifies the transaction ID from which updates will be retrieved. Only updates at or after this transaction ID will be included.

Return value

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

Examples

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:

pact
(keylog accounts "Alice" 123485945)
pact
(keylog accounts "Alice" 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.

keys

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

Basic syntax

(keys table)

Arguments

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

ArgumentTypeDescription
tabletable<{row}>Specifies the table from which to retrieve keys. The table schema is table:<{row}>, where row represents the structure of each row in the table.

Return values

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

Examples

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

pact
(defschema account  balance:decimal  owner:string) (deftable accounts:{account})
pact
(defschema account  balance:decimal  owner:string) (deftable accounts:{account})

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:

pact
pact>(keys accounts)[]
pact
pact>(keys accounts)[]

read

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

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
tabletable<{row}>Specifies the table from which to read the row. The table schema is table:<{row}>, where row represents the structure of each row in the table.
keystringSpecifies the key of the row to read from the table.
columns[string](Optional) Specifies an array of column names to return from the row. If not provided, the entire row is returned.

Return values

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

  • If columns is not provided, the function returns an object with the schema object:<{row}>, where row represents the structure of the entire row.
  • If columns is provided, the function returns an object containing only the specified columns from the row.

Examples

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

lisp
(defschema account  balance:decimal  ccy:string  owner:string) (deftable accounts:{account})
lisp
(defschema account  balance:decimal  ccy:string  owner:string) (deftable accounts:{account})

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:

pact
(read accounts id ['balance 'ccy])
pact
(read accounts id ['balance 'ccy])

select

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

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table from which to select rows.
COLUMNS[string](Optional) Specifies the list of columns to select from the table.
WHERErow:object:<{row}>Specifies the WHERE clause to apply to each row to determine inclusion.

Return value

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

Examples

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":

pact
(select people ['firstName 'lastName] (where 'name (= "Fatima")))
pact
(select people ['firstName 'lastName] (where 'name (= "Fatima")))

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

pact
(select people (where 'age (> 30)))
pact
(select people (where 'age (> 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.

txids

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

Basic syntax

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

(txids TABLE TXID)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table from which to retrieve txids.
TXIDintegerSpecifies the txid value to compare against.

Return value

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

Examples

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:

pact
(txids accounts 123849535)
pact
(txids accounts 123849535)

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

txlog

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

Basic syntax

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

(txlog TABLE TXID)

Arguments

Use the following arguments to specify the table and transaction ID (TXID) for retrieval using the txlog Pact function.

ArgumentTypeDescription
tabletable:<{row}>Specifies the table from which to retrieve updates.
TXIDintegerSpecifies the transaction ID (TXID) for which updates are to be retrieved.

Return value

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

Examples

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:

pact
(txlog accounts 123485945)
pact
(txlog accounts 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.

update

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.

Basic syntax

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

(update table key object)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table in which to update the entry.
KEYstringSpecifies the key for the entry to be updated.
OBJECTobject:<{row}>Specifies the object column data to be written for the key.

Return value

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

Examples

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:

pact
(update accounts id { "balance": (+ bal amount), "change": amount, "note": "credit" })
pact
(update accounts id { "balance": (+ bal amount), "change": amount, "note": "credit" })

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.

with-default-read

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.

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table from which to read the row.
KEYstringSpecifies the key for which to read the row.
DEFAULTSobject:<{row}>Specifies the defaults object containing values for missing columns.
BINDINGSbinding:<{row}>Specifies the bindings for columns to be bound.
BODY<a>Specifies the subsequent body statements to be executed.

Return value

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

Examples

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:

pact
(with-default-read accounts id { "balance": 0, "ccy": "USD" } { "balance":= bal, "ccy":= ccy }  (format "Balance for {} is {} {}" [id bal ccy]))
pact
(with-default-read accounts id { "balance": 0, "ccy": "USD" } { "balance":= bal, "ccy":= ccy }  (format "Balance for {} is {} {}" [id bal ccy]))

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.

with-read

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.

Basic syntax

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

(with-read TABLE KEY BINDINGS)

Arguments

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

ArgumentTypeDescription
TABLEtable:<{row}>Specifies the table from which to read the row.
KEYstringSpecifies the key for which to read the row.
BINDINGSbinding:<{row}>Specifies the bindings for columns to be bound.
BODY<a>Specifies the subsequent body statements to be executed.

Return value

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

Examples

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:

pact
(with-read accounts id { "balance":= bal, "ccy":= ccy }  (format "Balance for {} is {} {}" [id bal ccy]))
pact
(with-read accounts id { "balance":= bal, "ccy":= ccy }  (format "Balance for {} is {} {}" [id bal ccy]))

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.

write

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

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
tabletable:<{row}>Specifies the table in which to write the entry.
KEYstringSpecifies the key for the entry to be written.
OBJECTobject:<{row}>Specifies the object column data to be written for the key.

Return value

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

Examples

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:

pact
(write accounts id { "balance": 100.0 })
pact
(write accounts id { "balance": 100.0 })

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.