bvbrc.GenomeFeatureClient#

class bvbrc.GenomeFeatureClient(api_key=None)#

Data Type : genome_feature

Primary Key : feature_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
)

aa_length = Field('aa_length')#: integer

aa_sequence_md5 = Field('aa_sequence_md5')#: string

accession = Field('accession')#: string

alt_locus_tag = Field('alt_locus_tag')#: string

annotation = Field('annotation')#: string

brc_id = Field('brc_id')#: string

classifier_round = Field('classifier_round')#: integer

classifier_score = Field('classifier_score')#: number

codon_start = Field('codon_start')#: integer

date_inserted = Field('date_inserted')#: date

date_modified = Field('date_modified')#: date

end = Field('end')#: integer

feature_id = Field('feature_id')#

primary key

string

feature_type = Field('feature_type')#: string

figfam_id = Field('figfam_id')#: string

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

gene_id = Field('gene_id')#: number

genome_id = Field('genome_id')#: string

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

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

location = Field('location')#: string

na_length = Field('na_length')#: integer

na_sequence_md5 = Field('na_sequence_md5')#: string

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

og_id = Field('og_id')#: string

owner = Field('owner')#: string

p2_feature_id = Field('p2_feature_id')#: number

patric_id = Field('patric_id')#: string

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

pgfam_id = Field('pgfam_id')#: string

plfam_id = Field('plfam_id')#: string

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

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

protein_id = Field('protein_id')#: string

public = Field('public')#: boolean

refseq_locus_tag = Field('refseq_locus_tag')#: string

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

sequence_id = Field('sequence_id')#: string

sog_id = Field('sog_id')#: string

start = Field('start')#: integer

strand = Field('strand')#: string

taxon_id = Field('taxon_id')#: integer

uniprotkb_accession = Field('uniprotkb_accession')#: string

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

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