Pagination and search
Every server endpoint that lists things (such as /v4/genomes, /v4/asset_groups and /v4/recipes) is paged and can be filtered in two ways:
- Exact-match filters: parameters specific to each endpoint, such as
digest=abc123orname=example - Search: the
q,search_fieldsandoperatorparameters
You can use both at once: exact-match filters apply first, then search.
Pagination
Section titled “Pagination”Pagination follows the GA4GH page-based style. Clients retrieve data in pages, with these query parameters:
page: The page to return, counted from 0 (default: 0). A page past the last one is a400.page_size: Results per page (default: 100, at most 1000). Over 1000 is a400.
Every list has a fixed order that ends in a unique column, so walking the pages returns each row exactly once. Genomes come with the most asset groups first, then by species name, then by digest; with a search term, the best matches come first (see Genome search ranking). Page 0 of an empty list is an empty results, not an error. The last page is (total - 1) // page_size: stop when (page + 1) * page_size >= total.
Search
Section titled “Search”Search takes these query parameters:
q: The search query string.search_fields: Comma-separated list of fields to search within. If not specified, searches across all searchable fields for the endpoint.operator: How to match (defaultcontains):eq: Exact match (field equals the query string exactly).contains: Checks if the field contains the query string (case-insensitive). In adescriptionfield, the query must start a word:ratfinds "rat genome" and "(rat)", not "curated".starts_with: Checks if the field starts with the query string (case-insensitive).ends_with: Checks if the field ends with the query string (case-insensitive).
Multiple Search Fields
Section titled “Multiple Search Fields”With several fields in search_fields, a row matches if any one of them matches. For example:
?q=test&search_fields=name,descriptionwill return items where either the name OR description contains "test"?q=v1&search_fields=name,version&operator=starts_withwill return items where either the name OR version starts with "v1"
Searchable Fields by Endpoint
Section titled “Searchable Fields by Endpoint”- Genomes (
/genomes):digest,description,species,synonyms,assembly_source,assembly_accession,aliases - Aliases (
/aliases):name - Asset Groups (
/asset_groups):name - Assets (
/assets):name,digest,path - Asset Classes (
/asset_classes):name,version,description - Recipes (
/recipes):name,version,description - Staged assets (
/staged_assets):asset_digest,mode
The genome species field matches the genome's scientific name and, when its store publishes a species list, every name of its taxon (scientific, common and other common names). So brown rat finds Rattus norvegicus even where the listed common name is Norway rat. Each name is matched on its own under the usual operators.
The genome synonyms field holds other names of the genome itself, from the FHR record's genomeSynonym (GRCh38). Each name is matched on its own: eq must equal one whole name, starts_with and ends_with test the start and end of each name, and contains looks inside them.
Genome search ranking
Section titled “Genome search ranking”With a search term, genomes are listed best match first. Each genome gets the best rank of any of its names (aliases, species names, synonyms, digest, assembly source and accession) that matched; the usual order breaks ties. Names are compared without case, with punctuation read as spaces:
- Exact: a whole name is the query (
humanfor the common name "human",hg38for an alias). - Whole word: the query is a whole word of a name (
ratin "Norway rat" or "naked mole-rat"). - Word start: a word of a name starts with the query (
ratin "Rattus norvegicus"). - Anything else: the query is inside a word (
ratin "mRatBN7.2"), or only the description matched.
So ?q=rat lists Rattus norvegicus genomes first. Ranking only reorders; it never changes which genomes match or the total.
In genome responses, common_name is the species list's common name for the genome's taxon (genomes have none of their own), and list and detail rows carry a species object (taxon_id, scientific_name, common_name, synonyms), or null when the species list has no row for the genome's taxon.
Exact-Match Filters by Endpoint
Section titled “Exact-Match Filters by Endpoint”Each endpoint also supports specific exact-match filters:
- Genomes (
/genomes):digest,alias,has_assets(trueorfalse),taxon_id(NCBI taxon id) - Aliases (
/aliases):name,genome_digest - Asset Groups (
/asset_groups):genome_digest,asset_class,asset_group_name,asset_group_id - Assets (
/assets):name,asset_group_name,genome_digest,recipe_name,asset_group_id - Asset Classes (
/asset_classes):name,version - Recipes (
/recipes):output_asset_class,name,version - Archives (
/archives):digest,asset_digest,genome_digest
Example Requests
Section titled “Example Requests”Exact-Match Filters
Section titled “Exact-Match Filters”GET /v4/genomes?digest=abc123&alias=hg38GET /v4/assets?name=fasta&genome_digest=abc123GET /v4/recipes?output_asset_class=fasta&version=0.0.1GET /v4/genomes?has_assets=true&taxon_id=9606Generic Search
Section titled “Generic Search”GET /v4/recipes?operator=contains&page=0&page_size=100GET /v4/recipes?q=fasta&search_fields=name&operator=contains&page=0&page_size=100GET /v4/recipes?q=0.0.1&search_fields=version&operator=contains&page=0&page_size=100GET /v4/asset_groups?q=fas&search_fields=name&operator=starts_with&page=0&page_size=100GET /v4/genomes?q=f&search_fields=digest&operator=starts_with&page=1&page_size=100Combined Approach
Section titled “Combined Approach”GET /v4/genomes?digest=abc123&q=human&search_fields=description&operator=containsGET /v4/assets?genome_digest=abc123&q=fasta&search_fields=name,path&operator=containsExample Response Structure
Section titled “Example Response Structure”{ "results": [ { "id": 1, "name": "example_recipe", "version": "0.0.1" }, { "id": 2, "name": "another_recipe", "version": "0.0.2" } ], "pagination": { "page": 0, "page_size": 100, "total": 150 }}