bvbrc.query

bvbrc.query(*predicates: RQLExpr, select: Iterable[str | Field] = Ellipsis, sort: Iterable[str | Field] = Ellipsis, limit: int | Literal['max'] = Ellipsis, start: int = 0, **constraints: Any) → RQLQuery

Build an RQL query with specified predicates and options.

This function constructs a Resource Query Language (RQL) query object that can be used to search and filter data in the BV-BRC database. It accepts multiple predicates and various query options to customize the search behavior.

Parameters

*predicatesRQL.RQLExpr

Variable number of RQL expression objects that define the search criteria. These are combined using a logical AND operation.

selectiterable of str or RQL.Field, optional

Fields to include in the query results. Can be field names as strings or RQL.Field objects. If not specified, fields are returned based on the default behavior of the BV-BRC API (which may vary by return format).

sortiterable of str or RQL.Field, optional

Fields to sort the results by. Can be field names as strings or RQL.Field objects. Multiple fields create a multi-level sort. Sort direction must be specified with ‘+’ (ascending) or ‘-’ (descending).

limitint or “max”, optional

Maximum number of results to return. Can be an integer or the string “max” to return all matching results (up to a maximum of 25,000).

startint, default 0

Starting offset for pagination (0-based index).

**constraintsany

Additional keyword arguments that specify field constraints or filters. Each key-value pair represents a field name and its required value.

Returns

RQL.RQLQuery

A constructed RQL query object that can be submitted to the BV-BRC Data API using one of the provided Client objects.

Examples

Basic query with field constraints:

>>> import bvbrc as bv
>>> q = bv.query(species="Escherichia coli", limit=100)

Query with predicates and sorting:

>>> q = bv.query(
...     bv.fld("genome_length") > 5000000,
...     select=["genome_id", "genome_name", "genome_length"],
...     sort=["+genome_length"], # '+' means ascending and '-' means descending
...     limit=50
... )

Queries can also be built step by step:

>>> q = (
...     bv.query()
...     .filter(species="Escherichia coli")
...     .select("genome_id", "genome_name", "checkm_completeness")
...     .sort(-bv.fld("checkm_completeness"))
...     .limit(10)
... )

A query object can then be submitted using a Client object:

>>> client = bv.GenomeClient()
>>> response = client.submit_query(q)