bvbrc.ExperimentClient#

class bvbrc.ExperimentClient(api_key=None)#

Data Type : experiment

Primary Key : exp_id

get(id: str, *, return_format: str | ReturnFormat = ReturnFormat.JSON, timeout: float | tuple[float, float] | None = None) → BVBRCResponse#

Retrieve a specific record by its unique identifier.

Fetches a single data record from the BV-BRC database using its unique ID. This is useful when you know the exact identifier of the record you want to retrieve.

Parameters#

idstr: The unique identifier of the record to retrieve. The format depends on the datatype (e.g., genome IDs, feature IDs, etc.).
return_formatstr or ReturnFormat, default ReturnFormat.JSON: The desired format for the returned data. See the BV-BRC documentation for allowed return formats.
timeoutfloat or tuple, optional: Timeout for the HTTP request. Can be a single float (total timeout) or a tuple of (connect_timeout, read_timeout).

Returns#

BVBRCResponse: A response object (derived from the requests.Response object) containing the retrieved data and associated response metadata.

Examples#

Retrieve a genome by ID:

>>> import bvbrc as bv
>>> genome_client = bv.GenomeClient()
>>> response = genome_client.get("1313.5458")

Retrieve with custom format and timeout:

>>> response = genome_client.get(
...     "1313.5458",
...     return_format=bv.ReturnFormat.CSV,
...     timeout=30
... )

search(*predicates: RQLExpr, select: Iterable[str | Field] = Ellipsis, sort: Iterable[str | Field] = Ellipsis, limit: int | Literal['max'] = Ellipsis, start: int = 0, return_format: str | ReturnFormat = ReturnFormat.JSON, timeout: float | tuple[float, float] | None = None, **constraints: Any) → BVBRCResponse#

Search for records using provided parameters.

Sends a query to the BV-BRC API using Resource Query Language (RQL) expressions and field constraints. This is the primary method for finding records that match specific criteria.

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).
return_formatstr or ReturnFormat, default ReturnFormat.JSON: The desired format for the returned data. See the BV-BRC documentation for allowed return formats.
timeoutfloat or tuple, optional: Timeout for the HTTP request. Can be a single float (total timeout) or a tuple of (connect_timeout, read_timeout).
**constraintsany: Additional keyword arguments that specify field constraints or filters. Each key-value pair represents a field name and its required value.

Returns#

BVBRCResponse: A response object (derived from the requests.Response object) containing the query results and associated response metadata.

Examples#

Basic search with field constraints:

>>> import bvbrc as bv
>>> genome_client = bv.GenomeClient()
>>> response = genome_client.search(species="Escherichia coli", limit=10)

Advanced search with predicates:

>>> response = genome_client.search(
...     bv.fld("genome_length") > 5000000,
...     bv.fld("genome_status") == "Complete",
...     select=["genome_id", "genome_name", "genome_length"],
...     sort=["+genome_length"],
...     limit=50
... )

Or searching using the field attributes of the client object:

>>> response = genome_client.search(
...     genome_client.genome_length > 5000000,
...     genome_client.genome_status == "Complete",
...     select=[
...         genome_client.genome_id,
...         genome_client.genome_name,
...         genome_client.genome_length
...     ],
...     sort=[+genome_client.genome_length],
...     limit=50
... )

submit_query(query: RQLQuery, *, return_format: str | ReturnFormat = ReturnFormat.JSON, timeout: float | tuple[float, float] | None = None) → BVBRCResponse#

Submit a pre-built RQL query to the BV-BRC API.

This method is useful when you have already built a query using the bvbrc.query method and want to submit it with a client.

Parameters#

queryRQL.RQLQuery: A pre-built RQL query object containing the search criteria, field selections, sorting, and other query parameters.
return_formatstr or ReturnFormat, default ReturnFormat.JSON: The desired format for the returned data. See the BV-BRC documentation for allowed return formats.
timeoutfloat or tuple, optional: Timeout for the HTTP request. Can be a single float (total timeout) or a tuple of (connect_timeout, read_timeout).

Returns#

BVBRCResponse: A response object (derived from the requests.Response object) containing the query results and associated response metadata.

Examples#

Build and submit a query:

>>> import bvbrc as bv
>>> q = bv.query(
...     bv.fld("genome_name") == "Escherichia coli",
...     select=["genome_id", "genome_name"],
...     limit=10
... )
>>> client = bv.GenomeClient()
>>> response = client.submit_query(q)

Specify the return format:

>>> response = client.submit_query(
...     q,
...     return_format=bv.ReturnFormat.CSV
)

additional_data = Field('additional_data')#: array of strings

additional_metadata = Field('additional_metadata')#: array of case insensitive strings

biosets = Field('biosets')#: integer

date_inserted = Field('date_inserted')#: date

date_modified = Field('date_modified')#: date

detection_instrument = Field('detection_instrument')#: case insensitive string

doi = Field('doi')#: string

exp_description = Field('exp_description')#: case insensitive string

exp_id = Field('exp_id')#

primary key

string

exp_name = Field('exp_name')#: case insensitive string

exp_poc = Field('exp_poc')#: case insensitive string

exp_protocol = Field('exp_protocol')#: array of case insensitive strings

exp_title = Field('exp_title')#: case insensitive string

exp_type = Field('exp_type')#: case insensitive string

experimenters = Field('experimenters')#: case insensitive string

genome_id = Field('genome_id')#: array of strings

measurement_technique = Field('measurement_technique')#: case insensitive string

organism = Field('organism')#: array of case insensitive strings

pmid = Field('pmid')#: string

public_identifier = Field('public_identifier')#: string

public_repository = Field('public_repository')#: string

samples = Field('samples')#: integer

strain = Field('strain')#: array of case insensitive strings

study_description = Field('study_description')#: case insensitive string

study_institution = Field('study_institution')#: case insensitive string

study_name = Field('study_name')#: case insensitive string

study_pi = Field('study_pi')#: case insensitive string

study_title = Field('study_title')#: case insensitive string

taxon_id = Field('taxon_id')#: array of integers

taxon_lineage_ids = Field('taxon_lineage_ids')#: array of strings

treatment_amount = Field('treatment_amount')#: array of case insensitive strings

treatment_duration = Field('treatment_duration')#: array of case insensitive strings

treatment_name = Field('treatment_name')#: array of case insensitive strings

treatment_type = Field('treatment_type')#: array of case insensitive strings