bvbrc.RQL#

The Resource Query Language (RQL) module. Defines objects that are meant to make building RQL queries feel intuitive.

class bvbrc.RQL.Field(name: str)#

Represents a field in an RQL query.

This class provides a convenient interface for building RQL expressions involving database fields, supporting comparison operations and sorting.

Attributes#

namestr: The field name.

Examples#

>>> field = Field("genome_name")
>>> expr = field == "Mycobacterium"
>>> print(expr)
eq(genome_name,Mycobacterium)

>>> sort_field = +Field("genome_name")  # ascending sort
>>> print(sort_field)
+genome_name

isin(values: Iterable[Any]) → RQLExpr#

Create an ‘in’ RQL expression for checking if field value is in a list (i.e., the field must be equal to one of the values in the list).

Parameters#

valuesIterable[Any]: An iterable of values to check against.

Returns#

RQLExpr: An RQL ‘in’ expression.

Examples#

>>> field = Field("genome_name")
>>> expr = field.isin(["Mycobacterium", "Escherichia", "Salmonella"])
>>> print(expr)
in(genome_name,(Mycobacterium,Escherichia,Salmonella))

bvbrc.RQL.MAX_RESULTS = 25000#: The maximum number of results that BV-BRC will return for one request

class bvbrc.RQL.RQLExpr(expr: str)#

A Resource Query Language (RQL) expression.

This class represents a single RQL expression that can be combined with other expressions using logical operators (AND, OR) to build complex queries.

Attributes#

exprstr: The RQL expression string.

Examples#

>>> expr = RQLExpr("eq(genome_name,Mycobacterium)")
>>> print(expr)
eq(genome_name,Mycobacterium)

>>> combined = RQLExpr("eq(genome_name,Mycobacterium)") & RQLExpr("gt(contigs,1)")
>>> print(combined)
and(eq(genome_name,Mycobacterium),gt(contigs,1))

class bvbrc.RQL.RQLQuery(filter: RQLExpr | None = None, select: RQLExpr | None = None, sort: RQLExpr | None = None, limit: RQLExpr | None = None)#

A class representing an RQL query (i.e., a combination of RQL expressions).

This class provides a fluent interface for building complex RQL queries with filtering, selection, sorting, and limiting capabilities.

Attributes#

content_typestr: The content type for the RQL query. This is incorporated into the request header when the query is submitted.

Examples#

>>> query = RQLQuery.build(
...     Field("genome_name") == "Mycobacterium",
...     select=["genome_id", "genome_name"],
...     sort=["+genome_name"],
...     limit=100
... )
>>> print(query.expression)
and(eq(genome_name,Mycobacterium))&select(genome_id,genome_name)&sort(+genome_name)&limit(100,0)

classmethod build(*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 object.

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#

RQLQuery: A complete RQL query object.

Examples#

>>> query = RQLQuery.build(
...     Field("genome_name") == "Mycobacterium",
...     select=["genome_id", "genome_name"],
...     sort=["+genome_name"],
...     limit=100,
...     taxon_lineage_names="Bacteria"
... )
>>> print(query)
RQL query: 'and(eq(genome_name,Mycobacterium),eq(taxon_lineage_names,Bacteria))&select(genome_id,genome_name)&sort(+genome_name)&limit(100,0)'

property expression: str#

Get the full RQL query expression.

Returns#

str: The complete RQL query as a string. Any spaces are replaced by ‘+’.

Examples#

>>> query = RQLQuery(filter=RQLExpr("eq(genome_name,Mycobacterium)"))
>>> print(query.expression)
eq(genome_name%,Mycobacterium)

filter(*predicates: RQLExpr, **constraints: Any) → RQLQuery#

Add filter expressions to the query, replacing any previous filter expressions that the query may have contained.

The query object is copied before being modified, and then the copied instance is returned.

Parameters#

*predicatesRQL.RQLExpr: Variable number of RQL expression objects that define the search criteria. These are combined using a logical AND operation.
**constraintsany: Additional field=value keyword arguments that specify field constraints or filters. Each key-value pair represents a field name and its required value.

Returns#

RQLQuery: A new RQLQuery instance with the specified filters.

Examples#

>>> import bvbrc as bv
>>> query = bv.query().filter(
...     bv.fld("genome_name") == "Mycobacterium",
...     taxon_lineage_names="Bacteria"
... )
>>> print(query)
RQL query: 'and(eq(genome_name,Mycobacterium),eq(taxon_lineage_names,Bacteria))'

limit(count: int, start: int = 0) → RQLQuery#

Specifiy the limit for the number of results returned and (optionally) the starting index for the first result. Replaces the previously set limit if the query contained one.

Parameters#

countint: Maximum number of results to return.
startint, default 0: Starting offset for first result returned.

Returns#

RQLQuery: A new RQLQuery instance with the limit clause.

Examples#

>>> import bvbrc as bv
>>> query = bv.query().limit(100, start=50)  # Get results 50-149
>>> print(query)
RQL query: 'limit(100,50)'

property no_limit: bool#

Check if the query limit is set to None (unlimited).

Returns#

bool: True if the limit is set to None, False otherwise.

Examples#

>>> query = RQLQuery(limit=RQLExpr("limit(None,0)"))
>>> print(query.no_limit)
True

select(*fields: str | Field) → RQLQuery#

Specify which fields to include in query results, replacing the previous select expression if the query contained one.

The query object is copied before being modified, and then the copied instance is returned.

Parameters#

*fieldsUnion[str, Field]: Variable number of field names or Field objects to select.

Returns#

RQLQuery: A new RQLQuery instance with the select clause.

Examples#

>>> import bvbrc as bv
>>> query = bv.query().select(
...     "genome_id",
...     "genome_name",
...     "taxon_lineage_names"
... )
>>> print(query)
RQL query: 'select(genome_id,genome_name,taxon_lineage_names)'

sort(*fields: str | Field) → RQLQuery#

Specify sorting for query results. replacing any previously specified sorting that the query may have contained.

Parameters#

*fieldsUnion[str, Field]: Variable number of field names or Field objects to sort by. Fields must start with ‘+’ for ascending or ‘-’ for descending order.

Returns#

RQLQuery: A new RQLQuery instance with the sort clause.

Examples#

>>> import bvbrc as bv
>>> query = bv.query().sort("+genome_name", "-genome_length")
>>> print(query)
RQL query: 'sort(+genome_name,-genome_length)'

bvbrc.RQL.keyword(value: Any) → RQLExpr#

Create a keyword RQL search expression.

Keyword expressions are used to search for a keyword across all fields.

Parameters#

valueAny: The keyword or phrase to search for.

Returns#

RQLExpr: An RQL keyword search expression.

Examples#

>>> expr = keyword("mycobacterium tuberculosis")
>>> print(expr)
keyword(mycobacterium tuberculosis)