Global Search & Taxonomy Handling
Relevant source files
The following files were used as context for generating this wiki page:
Global Search and Taxonomy Handling within the DXKB platform provide a unified interface for querying biological data across multiple domains, including genomes, protein features, epitopes, and taxonomic classifications. The system is designed to sanitize complex user inputs, handle specialized biological identifiers (such as FIG IDs and EC numbers), and route queries to the appropriate specialized search views or a comprehensive multi-term results aggregator.
Taxonomy handling is a critical subset of this system, enabling users to pinpoint specific organisms via NCBI Taxonomy IDs or names. This metadata is integrated into both the search engine and specialized analysis services, ensuring that sequence data is correctly associated with its biological origin.
Global Search Architecture
The search system operates through a multi-stage pipeline: input normalization, identifier detection, and conditional routing.
Search Query Processing
The processing logic cleanses user input by removing or replacing characters that interfere with Solr/API queries. This includes stripping special characters like +, -, <, >, and /, and handling quoted phrases to ensure exact matching unless they contain structural brackets.
A key feature is the automatic detection of biological IDs. The system identifies patterns for FIG IDs (fig|...), Genome IDs (numeric strings with decimals), and IDs ending in numbers. When detected, these are automatically wrapped in quotes to ensure exact matching in the backend.
Sources: src/app/search/page.tsx:13-53, src/app/allTermSearchResults.tsx:55-88
Routing and Results Display
Queries are routed based on the searchtype parameter:
- Everything: Triggers a multi-core search across 15+ different data types (e.g., taxonomy, genome, strain, epitope).
- Specific Types: Routes to
TypeSearchfor focused queries on single resources likesurveillanceorexperiment.
Sources: src/app/search/page.tsx:56-82, src/app/allTermSearchResults.tsx:13-30
Multi-Term Search Logic
The following diagram illustrates the flow of a search request from the user interface through the processing and API retrieval stages.
The search system converts user strings into sanitized API payloads before fetching data from the BV-BRC Data API.
Sources: src/app/search/page.tsx:13-82, src/app/allTermSearchResults.tsx:280-318
Taxonomy Management
Taxonomy handling involves specialized components for selecting and validating NCBI Taxon IDs and names. This is utilized in both global search and in tools like the Subspecies Classification and Genome Annotation services.
Taxonomy Selection Components
The TaxIDSelector provides a debounced search interface against the taxonomy API. It allows users to search by Taxon ID and see the associated lineage and name. It uses react-query for caching results and managing the loading state during asynchronous fetches.
Sources: src/components/taxonomy/tax-id-selector.tsx:43-116
Taxonomic Data Model
The system retrieves and displays the following fields for taxonomic entries:
| Field | Description | Source |
|---|---|---|
taxon_id | Unique numerical identifier assigned by NCBI | src/lib/services/service-info.ts:169 |
taxon_name | The scientific name of the organism | src/components/taxonomy/tax-id-selector.tsx:28 |
lineage_names | Hierarchical classification path (e.g., Genus > Species) | src/components/taxonomy/tax-id-selector.tsx:28 |
genomes | The count of genomes associated with this taxon | src/app/allTermSearchResults.tsx:227 |
Service Integration
Taxonomy data is used to drive service parameters. For example, in the Subspecies Classification service, the "Species" selection determines the reference tree and alignment used by tools like pplacer and Cladinator.
Taxonomy selection is a prerequisite for many biological analysis services within the platform.
Sources: src/components/taxonomy/tax-id-selector.tsx:27-41, src/lib/services/service-info.ts:145-155
Search Interface Variations
The platform provides multiple entry points for searching and filtering data.
1. Global Welcome Search
The hero section on the homepage offers three search modes:
- Basic Search: A standard keyword search with "popular" tags like SARS-CoV-2.
- Advanced Search: Field-specific filters for Taxonomy, Host, Genome Type, and Protein Function.
- Sequence Search: A direct interface for pasting FASTA sequences (Nucleotide or Protein).
Sources: src/components/search/welcome-search.tsx:55-125
2. Specialized List Views
Specific modules, such as Publications and Citations, implement their own search and filter logic locally. These include year range filters, publication type checkboxes, and sort options (Newest, Most Cited).
Sources: src/app/(footer)/publications/page.tsx:75-115, src/app/(footer)/citations/page.tsx:44-59
Implementation Details
Identifier Patterns
The search utility uses specific Regex patterns to identify and protect biological identifiers during the sanitization process:
| Pattern | Matches | Action |
|---|---|---|
/^fig|[0-9]+/ | FIG IDs (e.g., fig|83332.12.peg.1) | Wrap in quotes |
/[0-9]+\.[0-9]+/ | Decimal IDs (e.g., 83332.12) | Wrap in quotes |
/[0-9]+$/ | Strings ending in digits | Wrap in quotes |
Sources: src/app/search/page.tsx:43-51, src/app/allTermSearchResults.tsx:76-85
API Request Construction
In "Everything" search mode, a single POST request is sent to the /query/ endpoint with a payload containing sub-queries for every data type.
// src/app/allTermSearchResults.tsx:287-306
searchTypes.forEach((searchType) => {
let tq = processedQuery;
switch (searchType) {
case "genome_feature":
tq += "&ne(annotation,brc1)&ne(feature_type,source)";
break;
case "taxonomy":
tq += ">(genomes,1)";
break;
}
searchPayload[searchType] = {
dataType: searchType,
accept: "application/solr+json",
query: tq + "&limit(3)&sort(-score)",
};
});
This multi-query structure allows the UI to present a "Results Overview" that tallies hits across diverse databases simultaneously.
Sources: src/app/allTermSearchResults.tsx:287-318
Conclusion
Global Search & Taxonomy Handling forms the backbone of the DXKB data discovery layer. By combining aggressive string sanitization with specialized biological ID detection and a robust taxonomy selection system, the project ensures that researchers can accurately bridge the gap between simple text queries and complex bioinformatic data structures. The integration of these components into specialized analysis services further ensures data integrity across the platform's computational workflows.