corda / net.corda.core.messaging / CordaRPCOps / vaultQueryBy


@RPCReturnsObservables abstract fun <T : ContractState> vaultQueryBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort, contractStateType: Class<out T>): Page<T>

Returns a snapshot of vault states for a given query criteria (and optional order and paging specification)

Generic vault query function which takes a QueryCriteria object to define filters, optional PageSpecification and optional Sort modification criteria (default unsorted), and returns a Vault.Page object containing the following:

  1. states as a List of (page number and size defined by PageSpecification)
  2. states metadata as a List of Vault.StateMetadata held in the Vault States table.
  3. total number of results available if PageSpecification supplied (otherwise returns -1)
  4. status types used in this query: UNCONSUMED, CONSUMED, ALL
  5. other results (aggregate functions with/without using value groups)


VaultQueryException -

if the query cannot be executed for any reason (missing criteria or parsing error, paging errors, unsupported query, underlying database error)

Notes If no PageSpecification is provided, a maximum of DEFAULT_PAGE_SIZE results will be returned. API users must specify a PageSpecification if they are expecting more than DEFAULT_PAGE_SIZE results, otherwise a VaultQueryException will be thrown alerting to this condition. It is the responsibility of the API user to request further pages and/or specify a more suitable PageSpecification.