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.
Argument | Type | Description |
---|---|---|
TABLE | table:<{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:
(create-table accounts)
(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.
Argument | Type | Description |
---|---|---|
keyset | string | Specifies 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:
pact> (describe-keyset 'admin-keyset){ "pred": "keys-all", "keys": [ "ba54b224d1924dd98403f5c751abdd10de6cd81b0121800bf7bdbdcfaec7388d", "8cc94f8a4b43f4d9e3f8c5dca3966ea000f13ecbd79abc01bc7c00faacd06a5e" ]}
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.
Argument | Type | Description |
---|---|---|
table | table:<{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>(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>(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:
Argument | Type | Description |
---|---|---|
TABLE | table:<{row}> | Specifies the table from which to select rows. |
QRY | a:string b:object:<{row}> -> bool | Specifies the predicate function to apply to each row. |
CONSUMER | a: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:
(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))
(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.
Argument | Type | Description |
---|---|---|
table | table<{row}> | Specifies the table where the entry will be written. |
key | string | Specifies the key for which the data will be inserted. |
object | object<{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:
(insert accounts id { "balance": 0.0, "note": "Created account." })
(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.
Argument | Type | Description |
---|---|---|
table | table<{row}> | Specifies the table from which updates will be retrieved. |
key | string | Specifies the key for which updates will be retrieved. |
txid | integer | Specifies 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:
(keylog accounts "Alice" 123485945)
(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.
Argument | Type | Description |
---|---|---|
table | table<{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:
(defschema account balance:decimal owner:string) (deftable accounts:{account})
(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>(keys accounts)[]
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.
Argument | Type | Description |
---|---|---|
table | table<{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. |
key | string | Specifies 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 schemaobject:<{row}>
, whererow
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:
(defschema account balance:decimal ccy:string owner:string) (deftable accounts:{account})
(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:
(read accounts id ['balance 'ccy])
(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.
Argument | Type | Description |
---|---|---|
TABLE | table:<{row}> | Specifies the table from which to select rows. |
COLUMNS | [string] | (Optional) Specifies the list of columns to select from the table. |
WHERE | row: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":
(select people ['firstName 'lastName] (where 'name (= "Fatima")))
(select people ['firstName 'lastName] (where 'name (= "Fatima")))
To select all columns from the people
table where the age
is less than 30:
(select people (where 'age (> 30)))
(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.
Argument | Type | Description |
---|---|---|
TABLE | table:<{row}> | Specifies the table from which to retrieve txids. |
TXID | integer | Specifies 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:
(txids accounts 123849535)
(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.
Argument | Type | Description |
---|---|---|
table | table:<{row}> | Specifies the table from which to retrieve updates. |
TXID | integer | Specifies 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
:
(txlog accounts 123485945)
(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.
Argument | Type | Description |
---|---|---|
TABLE | table:<{row}> | Specifies the table in which to update the entry. |
KEY | string | Specifies the key for the entry to be updated. |
OBJECT | object:<{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:
(update accounts id { "balance": (+ bal amount), "change": amount, "note": "credit" })
(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.
Argument | Type | Description |
---|---|---|
TABLE | table:<{row}> | Specifies the table from which to read the row. |
KEY | string | Specifies the key for which to read the row. |
DEFAULTS | object:<{row}> | Specifies the defaults object containing values for missing columns. |
BINDINGS | binding:<{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:
(with-default-read accounts id { "balance": 0, "ccy": "USD" } { "balance":= bal, "ccy":= ccy } (format "Balance for {} is {} {}" [id bal ccy]))
(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.
Argument | Type | Description |
---|---|---|
TABLE | table:<{row}> | Specifies the table from which to read the row. |
KEY | string | Specifies the key for which to read the row. |
BINDINGS | binding:<{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:
(with-read accounts id { "balance":= bal, "ccy":= ccy } (format "Balance for {} is {} {}" [id bal ccy]))
(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.
Argument | Type | Description |
---|---|---|
table | table:<{row}> | Specifies the table in which to write the entry. |
KEY | string | Specifies the key for the entry to be written. |
OBJECT | object:<{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:
(write accounts id { "balance": 100.0 })
(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.