fluree.db.api — com.fluree/db 1.0.0-rc1

account-id clj

(account-id public-key)

(account-id message signature)

Returns account id from either a public key or message and signature.

auth-match clj

(auth-match auth-set t-map flake)

block-event->map clj

(block-event->map conn ledger block-event)

Takes block event data from (listen...) and adds an :added and :retracted key containing maps of data organized by subject and containing full predicate names.

block-query-async clj

(block-query-async conn ledger query-map)

block-range clj

(block-range db start)

(block-range db start end)

(block-range db start end opts)

Returns a core async channel of blocks from start block (inclusive) to end if provided (exclusive). Each block is a separate map, containing keys :block, :t and :flakes. Channel is lazy, continue to take! values as needed.

block-range-with-txn-async clj

(block-range-with-txn-async conn ledger block-map)

Returns a core async channel of blocks from start block (inclusive) to end if provided (exclusive). Each block is a separate map, containing keys :block, :t, :flakes and :txn

close clj

(close conn)

Closes connection.

close-listener clj

(close-listener conn ledger key)

Closes a listener.

collection-flakes clj

(collection-flakes db collection)

collection-id clj

(collection-id db collection)

Returns promise containing id of a collection, given a collection name. Returns nil if collection doesn't exist.

connect clj

(connect ledger-servers & [opts])

Connect to a ledger server using URL address. If using a ledger group, multiple addresses can be supplied, separated by commas.

db clj

(db conn ledger)

(db conn ledger opts)

Returns a queryable database from the connection for the specified ledger.

delete-ledger clj

(delete-ledger conn ledger)

(delete-ledger conn ledger opts)

delete-ledger-async clj

(delete-ledger-async conn ledger)

(delete-ledger-async conn ledger opts)

Completely deletes a ledger. Returns a future that will have a response with a corresponding status of success.

A 200 status indicates the deletion has been successfully initiated. The full deletion happens in the background on the respective ledger.

Query servers get notified when this process initiates, and ledger will be marked as being in a deletion state during the deletion process.

Attempts to use a ledger in a deletion state will throw an exception.

flakes clj

(flakes conn)

(flakes conn start)

(flakes conn start end)

(flakes conn start end {:keys [subject predicate limit offset chunk]})

Returns a lazy sequence of raw flakes from the blockchain history from start block/transaction (inclusive) to end block/transaction (exclusive).

A nil start defaults to the genesis block. A nil end includes the last block of the known database. A positive integer for either start/end indicates a block number, a negative integer indicates a transaction number.

Results can potentially include the entire database depending on your filtering criteria, so be sure to only 'pull' items as you need them.

The optional map of filter criteria has the following keyed options:

:subject - Limit results to only include history of this subject, specified as either an _id or identity. Note the results are no longer lazy when using this option. :predicate - Limit results to only include history for this predicate. Must be used in conjunction with subject. If there is a need to get history of all subjects for a specific predicate, see 'range-history'. :limit - Limit results to this quantity of matching flakes :offset - Begin results after this number of matching flakes (for paging - use in conjunction with limit) :chunk - Results are fetched in chunks. Optionally specify the size of a chunk if optimization is needed.

format-block-resp-pretty clj

(format-block-resp-pretty db curr-block cache fuel)

format-blocks-resp-pretty clj

(format-blocks-resp-pretty db resp)

format-history-resp clj

(format-history-resp db resp auth show-auth)

forward-time-travel clj

(forward-time-travel db flakes)

Returns a core async chan with a new db based on the provided db, including the provided flakes. Flakes can contain one or more 't's, but should be sequential and start after the current 't' of the provided db. (i.e. if db-t is -14, flakes 't' should be -15, -16, etc.). Remember 't' is negative and thus should be in descending order.

A forward-time-travel db can be further forward-time-traveled.

A forward-time travel DB is held in memory, and is not shared across servers. Ensure you have adequate memory to hold the flakes you generate and add. If access is provided via an external API, do any desired size restrictions or controls within your API endpoint.

Remember schema operations done via forward-time-travel should be done in a 't' prior to the flakes that end up requiring the schema change.

forward-time-travel-db? clj

(forward-time-travel-db? db)

Returns true if provided db is a forward-time-travel db.

get-db-at-block clj

(get-db-at-block conn ledger block every-n-sec)

get-history-pattern clj

(get-history-pattern history)

graphql-async clj

(graphql-async conn db-name query-map)

Execute a graphql query against the specified database. Query must come in as a map with keys:

• query - required graphql string query
• variables - optional substitution variables supplied with query
• opts - optional map of options (same as flureeQL :opts map), however not all options would be relevant for graphql

history-query clj

(history-query sources query-map)

history-query-async clj

(history-query-async sources query-map)

index clj

(index db index start stop)

Returns a raw collection of flakes from the specified index as a lazy sequence.

Optionally specify a start and/or stop point to restrict the collection to a range along with an operator of <, <=, >, >=. If you wish to restrict to a specific subject, predicate, etc. the = operator can also be used, which is equivalent to the same parts being specified with a >= and <= operators.

The start and stop point should be specified as a vector of the relevant part(s) of the specified index. i.e. if using the :spo index, the parts are [s p o], an :pos index would be [p o s]. If only some parts, i.e. [s] are provided, the other parts are assumed to be the lowermost or uppermost bounds of the remaining parts depending on if it is the start or stop respectively. Keep in mind subjects sort descending.

Entities can be specified as an _id long integer, any unique identity (pred / obj two-tuple), or a collection name.

Predicates can b

latest-block clj

(latest-block conn ledger)

Returns latest block (positive integer) for a local ledger. Will bring the ledger locally if not already local.

latest-t clj

(latest-t conn ledger)

Returns latest t (negative integer) for a local ledger. Will bring the ledger locally if not already local.

ledger-info clj

(ledger-info conn ledger)

Returns promise with ledger's status as a map, including index, indexes, block, and status. If ledger doesn't exist, will return an empty map.

ledger-info-async clj

(ledger-info-async conn ledger)

Returns core async promise channel with ledger's status as a map, including index, indexes, block, and status. If ledger doesn't exist, will return an empty map.

ledger-list clj

(ledger-list conn)

Returns promise with a list of ledgers the connected server is currently serving.

ledger-list-async clj

(ledger-list-async conn)

Returns a list of ledgers the connected server is currently serving. Returns core async promise channel with response.

ledger-ready? clj

(ledger-ready? conn ledger)

Returns true or false if ledger is in a 'ready' status.

ledger-ready?-async clj

(ledger-ready?-async conn ledger)

Returns core async channel that will be true or false if ledger is in a 'ready' status.

ledger-stats clj

(ledger-stats conn ledger)

Returns promise with ledger info, including db size and # of flakes. If ledger doesn't exist, will return an empty map.

ledger-stats-async clj

(ledger-stats-async conn ledger)

Returns core async promise channel with ledger info, including db size and # of flakes. If ledger doesn't exist, will return an empty map.

listen clj

(listen conn ledger key fn)

Listens to all events of a given ledger. Supply a ledger identity, any key, and a two-argument function that will be called with each event.

The key is any arbitrary key, and is only used to close the listener via close-listener, otherwise it is opaque to the listener.

The callback function's first argument is the event header/metadata and the second argument is the event data itself.

min-safe clj

(min-safe & args)

monitor-tx-async clj

(monitor-tx-async conn ledger tid timeout-ms)

Monitors a database for a specific transaction id included in a block.

Returns a core async channel that will eventually contain a response, or will close after the timeout has expired.

Response may contain an exception, if the tx resulted in an exception.

multi-query clj

(multi-query sources multi-query-map)

multi-query-async clj

(multi-query-async sources multi-query-map)

Like query, but takes a map of multiple queries - where map keys are any user-provided aliases and values are queries as if sent directly to 'query'.

If not {:meta true}, any responses with errors will not be returned.

If {:meta true} -> The response :result contains all provided queries, with keys being the same user-provided aliases and values being the query results only.

Queries with any non-200 response will not be included in the :result, but will be in a separate :errors key containing the error(s) using their respective aliases.

If all queries have the identical error status, the overall response status will be that status. If some queries are 200 status but others have errors, the overall response will be a 207 (WevDAV's multi-status response) If all queries have error responses, but mixed, the overall response will be 400 unless there is also a 5xx status code, in which case it will be 500.

Queries leverage multi-threading.

All queries are for the same block. :block can be included on the main map. Whether or not a block is specified in the main map, any of the individual queries specify a block, it will be ignored.

multi-txns-async clj

(multi-txns-async conn ledger txns)

(multi-txns-async conn ledger txns opts)

new-ledger clj

(new-ledger conn ledger)

(new-ledger conn ledger opts)

new-ledger-async clj

(new-ledger-async conn ledger)

(new-ledger-async conn ledger opts)

Attempts to create new ledger.

A successful result will kick off a process on the ledger server(s) to bootstrap.

Once successful, will return with a command-id.

Ledger creation is handled asynchronously and may not be immediately available.

Options include:

• :alias - Alias, if different than db-ident.
• :root - Root account id to bootstrap with (string). Defaults to connection default account id.
• :doc - Optional doc string about this db.
• :fork - If forking an existing db, ref to db (actual identity, not db-ident). Must exist in network db.
• :forkBlock - If fork is provided, optionally provide the block to fork at. Defaults to latest known.
• :persistResp - Respond immediately once persisted with the dbid, don't wait for transaction to be finished

new-private-key clj

(new-private-key)

Generates a new private key, returned in a map along with the public key and account id. Return keys are :public, :private, and :id.

predicate-id clj

(predicate-id db predicate)

Returns promise containing predicate id given a predicate name, or predicate id. If predicate doesn't exist, returns nil.

predicate-name clj

(predicate-name db predicate-name)

Returns promise containing predicate name given predicate id.

public-key clj

(public-key message signature)

Returns a public key from a message and a signature.

public-key-from-private clj

(public-key-from-private private-key)

Returns a public key given a private key.

query clj

(query sources query-map)

Execute a query against a database source, or optionally additional sources if the query spans multiple data sets. Returns promise with result.

query-async clj

(query-async sources query-map)

Execute a query against a database source, or optionally additional sources if the query spans multiple data sets. Returns core async channel containing result.

query-with-async clj

(query-with-async sources param)

range clj

(range & args)

Returns a lazy sequence of raw flakes for the database and specified index. Results can be limited by including one or two match clauses, in addition to options including a limit and offset.

Match predicates can be one of: =, >, >=, <, <= as either a string or symbol. If two matches are provided, one must be a > or >=, and the other a < or <=. An = predicate is only allowed with a single match statement, and acts the same providing two match statements: >= match <= match]

Matches are a vector containing the flake components desired for a match, in the order dictated by the specified index. For example, if an spot index is used, the order is [s, p, o]. If an post index is used, the order is [p, o, s]. The match vector can be a one, two, or three-tuple depending on the specificity desired for the match. For example, for an spot index where the match should include all predicates from subject 42, the match clause could be either [42], [42, nil] or [42, nil, nil]. Unlike the 'flakes' function, nil values in a match are only valid if no non-nil value follows.

Opts may be provided. opts is a map containing any of the optional keys:

:limit - Limit results to this quantity :history - Return the history of this range :from-block - Only applicable for history, return history up until a certain block :chunk - Results are fetched in chunks. Optionally specify the size of a chunk if optimization is needed. :test - Running as a test. Makes sure, i.e. index ranges are not cached.

resolve-block-range clj

(resolve-block-range db query-map)

resolve-ledger clj

(resolve-ledger conn ledger)

Resolves a ledger identity in the form of 'network/ledger-or-alias' and returns a two-tuple of [network ledger].

An alias lookup is always performed first, and if an alias doesn't exist it is assumed the provided name is a ledger id.

If you are providing a ledger id, and wish to skip an alias lookup, a prefix of '$' can be used for the name portion of the db-ident.

i.e.

• testnet/testledger - Look for ledger with an alias or id of testledger on network testnet.
• testnet/$testledger - look for a ledger with id testledger on network testnet (skip alias lookup).

search clj

(search db flake-parts)

Returns a promise containing search results of flake parts (fparts).

search-async clj

(search-async db flake-parts)

Performs a search for matching flakes, returns a core async promise channel.

session clj

(session conn ledger)

Returns actual session object for a given ledger.

set-default-key-async clj

(set-default-key-async conn private-key)

(set-default-key-async conn network private-key)

(set-default-key-async conn network dbid private-key)

(set-default-key-async conn network dbid private-key opts)

Sets a new default private key for the entire tx-group, network or db level. This will only succeed if signed by the default private key for the tx-group, or if setting for a dbid, either the tx-group or network.

It will overwrite any existing default private key.

Returns core async channel that will respond with true or false.

sign clj

(sign message private-key)

Returns a signature for a message given provided private key.

sparql-async clj

(sparql-async db sparql-str)

(sparql-async db sparql-str opts)

Exceute a sparql query against a specified database

sql-async clj

(sql-async db sql-str)

(sql-async db sql-str opts)

Execute an SQL query against a specified database

subid clj

(subid db ident)

Returns promise containing subject id given a subject identity, or subject id. If subject doesn't exist, returns nil.

subid-async clj

(subid-async db ident)

Like subid, but returns a core async promise channel instead of a promise.

submit-command-async clj

(submit-command-async conn command)

Submits a fully signed command to the connected ledger group. Commands have two required keys:

• cmd - a map with the transactional data as a JSON string
• sig - the signature of the stringified tx map

Command ids are the sha3 of the cmd, and can be used to reference command status or look them up (i.e. a transaction command id is the txid.)

The stringified cmd contains a payload that is a map, a transaction example follows:

{:type tx - command type is required on all commands :db testnet/mydb - db name, use testnet/$mydb to peg to a dbid :tx [{...}, {...}] - transactional data :auth ABC12345676 - only required if using an authority's signature, else inferred from signature :fuel 10000 - max fuel to spend, only required if enforcing fuel limits. tx will fail if auth doesn't have this much fuel avail. Will fail if all fuel is consumed. Unused fuel will not be debited. :nonce 1234 - nonce ensures uniqueness, making sure two identical transactions have different txids :expire 1547049123614 - don't even attempt this transaction after this moment in time :deps [] - optional one or more txids that must execute successfully before this tx executes if any of the txs in deps fail, this tx will fail }

Attempting to cancel a transaction {:type tx-cancel :txid DSFGFHSDDF - txid you wish to cancel }

A new ledger command looks like: Note new ledgers are issued as a command, and auth/signature should have proper authority on ledger servers. {:type new-db - command type is required on all commands :db testnet/mydb - db name - as network/dbid :alias testnet/mydb - optional alias, will default to 'db' if not specified. :fork testnet/forkdb - optional name of db to fork, if forking. Use testnet/$forkdb to peg to a dbid :forkBlock 42 - if forking a db, optionally provides a block to fork at, else will default to current block :auth ABC12345676 - only required if using an authority's signature :fuel 10000 - max fuel to spend, only required if enforcing fuel limits. tx will fail if auth doesn't have this much fuel avail. Will fail if all fuel is consumed. Unused fuel will not be debited. :nonce 1234 - nonce ensures uniqueness, making sure two identical transactions have different txids :expire 1547049123614 - don't even attempt this transaction after this moment in time }

transact clj

(transact conn ledger txn)

(transact conn ledger txn opts)

Like transact-async, but returns a promise.

transact-async clj

(transact-async conn ledger txn)

(transact-async conn ledger txn opts)

Submits a transaction for a ledger and a transaction. Returns a core async channel that will eventually have the result of the tx, the txid (if :txid-only option used), or an exception due to an invalid transaction or if the timeout occurs prior to a response.

Will locally sign a final transaction command if a private key is provided via :private-key in the options, otherwise will submit the transaction to the connected ledger and request signature, provided the ledger group has a default private key available for signing.

Options (opts) is a map with the following possible keys:

• private-key - The private key to use for signing. If not present, a default private key will attempt to be used from the connection, if available.
• auth - The auth id for the auth record being used. The private key must correspond to this auth record, or an authority of this auth record.
• expire - When this transaction should expire if not yet attempted. Defaults to 5 minutes.
• nonce - Any long/64-bit integer value that will make this transaction unique. By default epoch milliseconds is used.
• deps - List of one or more txids that must be successfully processed before this tx is processed. If any fail, this tx will fail. (not yet implemented)
• txid-only - Boolean (default of false). If true, will not wait for a response to the tx, but instead return with the txid once it is successfully persisted by the transactors. The txid can be used to look up/monitor the response at a later time.
• timeout - will respond with an exception if timeout reached before response available.

tx->command clj

(tx->command ledger txn private-key)

(tx->command ledger txn private-key opts)

Helper function to fill out the parts of the transaction that are incomplete, producing a signed command.

Optional opts is a map with the following keys. If not provided, defaults will be attempted.

• auth - The auth id for the auth record being used. The private key must correspond to this auth record, or an authority of this auth record.
• expire - When this transaction should expire if not yet attempted. Defaults to 5 minutes.
• nonce - Any long/64-bit integer value that will make this transaction unique. By default epoch milliseconds is used.
• deps - Not yet implemented, list of dependent transactions.

If successful, will return a map with four keys:

• cmd - a map with the command/transaction data as a JSON string
• sig - the signature of the above stringified map
• id - the ID for this unique request - in case you want to look it up later, sha3 of 'cmd'
• db - the ledger for this transaction

wait-for-ledger-ready clj

(wait-for-ledger-ready conn ledger)

(wait-for-ledger-ready conn ledger timeout)

Will block until ledger is in ready status and return true, or if supplied timeout in milliseconds expires, will return nil. Defaults timeout to 30000 if two-arity call is used.

wait-for-ledger-ready-async clj

(wait-for-ledger-ready-async conn ledger timeout)

Returns core async channel that will return true when ledger is in ready status or if timeout in ms supplied expires, will close the channel (returning nil).