`CollectionSearch` Subclasses¶

Collection-specific subclasses are the recommended public entry points. Each class inherits CollectionSearch behavior while preconfiguring a collection target.

Choosing a Subclass¶

Pick the subclass matching the record type you want to query.
Use inherited methods such as get_record_by_id, get_record_by_attribute, get_record_by_filter, and get_records.
See Using MongoDB Filters for query construction and operator examples.
NMDC Schema reference: https://microbiomedata.github.io/nmdc-schema/
Typecode-to-class map: https://microbiomedata.github.io/nmdc-schema/typecode-to-class-map/

These classes focus on study-level and site-level discovery. Use them when starting from study metadata, biosamples, or collection events.

BiosampleSearch ¶

BiosampleSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch, nmdc_client.lat_long_filters.LatLongFilters

Class to interact with the NMDC API to search for records within the biosample_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/biosample_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="biosample_set",
        api_base_url=api_base_url,
        env=env,
    )

StudySearch ¶

StudySearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the study_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/study_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="study_set",
        api_base_url=api_base_url,
        env=env,
    )

CollectingBiosamplesFromSiteSearch ¶

CollectingBiosamplesFromSiteSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the collecting_biosamples_from_site_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/collecting_biosamples_from_site_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="collecting_biosamples_from_site_set",
        api_base_url=api_base_url,
        env=env,
    )

FieldResearchSiteSearch ¶

FieldResearchSiteSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.lat_long_filters.LatLongFilters, nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the field_research_site_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/field_research_site_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="field_research_site_set",
        api_base_url=api_base_url,
        env=env,
    )

These classes target records produced through sample processing lifecycle, including processed sample entities and upstream material/storage processes. Use NMDC Schema docs to confirm class semantics and filterable fields.

ProcessedSampleSearch ¶

ProcessedSampleSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the processed_sample_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/processed_sample_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="processed_sample_set",
        api_base_url=api_base_url,
        env=env,
    )

MaterialProcessingSearch ¶

MaterialProcessingSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the material_processing_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/material_processing_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="material_processing_set",
        api_base_url=api_base_url,
        env=env,
    )

StorageProcessSearch ¶

StorageProcessSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the storage_process_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/storage_process_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="storage_process_set",
        api_base_url=api_base_url,
        env=env,
    )

These classes cover records tied to generation setup and instrumentation. Use schema and typecode map when selecting classes for linked-instance queries.

DataGenerationSearch ¶

DataGenerationSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the data_generation_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/data_generation_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="data_generation_set",
        api_base_url=api_base_url,
        env=env,
    )

ManifestSearch ¶

ManifestSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the manifest_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/manifest_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="manifest_set",
        api_base_url=api_base_url,
        env=env,
    )

InstrumentSearch ¶

InstrumentSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the instrument_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/instrument_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="instrument_set",
        api_base_url=api_base_url,
        env=env,
    )

ConfigurationSearch ¶

ConfigurationSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the configuration_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/configuration_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="configuration_set",
        api_base_url=api_base_url,
        env=env,
    )

These classes are useful for workflow context, calibration context, data objects, and functional annotation aggregation outputs. Use NMDC Schema docs for exact field meanings and schema class names.

WorkflowExecutionSearch ¶

WorkflowExecutionSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the workflow_execution_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/workflow_execution_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="workflow_execution_set",
        api_base_url=api_base_url,
        env=env,
    )

CalibrationSearch ¶

CalibrationSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the calibration_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/calibration_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="calibration_set",
        api_base_url=api_base_url,
        env=env,
    )

DataObjectSearch ¶

DataObjectSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.collection_search.CollectionSearch

Class to interact with the NMDC API to search for records within the data_object_set collection.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/data_object_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        collection_name="data_object_set",
        api_base_url=api_base_url,
        env=env,
    )

get_data_objects_for_studies ¶

get_data_objects_for_studies(study_id: str, max_page_size: Optional[int] = None) -> list[dict]

Deprecated alias for get_data_objects_for_study.

Deprecated

Deprecated since version 0.7.0. Use get_data_objects_for_study instead.

Source code in nmdc_client/data_object_search.py

@has_deprecated_parameter("max_page_size", reason="It has no effect.")
@deprecated(reason="Use ``get_data_objects_for_study`` instead.", version="0.7.0")
def get_data_objects_for_studies(
    self,
    study_id: str,
    max_page_size: Optional[int] = None,
) -> list[dict]:
    """
    Deprecated alias for `get_data_objects_for_study`.

    !!! warning "Deprecated"

        Deprecated since version 0.7.0. Use `get_data_objects_for_study` instead.
    """
    _ = max_page_size
    return self.get_data_objects_for_study(study_id)

get_data_objects_for_study ¶

get_data_objects_for_study(study_id: str) -> list[dict]

Get all data objects related to the specified study.

Parameters:

Name	Type	Description	Default
`study_id`	`str`	The ID of the study.	required

Returns:

Type	Description
`list[dict]`	The data objects.

Raises:

Type	Description
`RuntimeError`	If the API request fails.

Source code in nmdc_client/data_object_search.py

def get_data_objects_for_study(self, study_id: str) -> list[dict]:
    """
    Get all data objects related to the specified study.

    Parameters
    ----------
    study_id
        The ID of the study.

    Returns
    -------
    list[dict]
        The data objects.

    Raises
    ------
    RuntimeError
        If the API request fails.
    """

    url = f"{self.api_base_url}/data_objects/study/{study_id}"
    try:
        response = requests.get(
            url,
            headers=self._build_http_request_headers(),
        )
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        logger.error("API request failed", exc_info=True)
        raise RuntimeError("Failed to get data_objects from NMDC API") from e
    else:
        logging.debug(
            f"API request response: {response.json()}\n API Status Code: {response.status_code}"
        )

    results = response.json()

    return results

FunctionalAnnotationAggSearch ¶

FunctionalAnnotationAggSearch(api_base_url: str = 'https://api.microbiomedata.org', env: str = '')

Bases: nmdc_client.functional_search.FunctionalSearch

Class to interact with the NMDC API to search for records within the functional_annotation_agg collection.

These are most helpful when trying to identify workflows associated with a KEGG, COG, or PFAM ids.

Warnings

The env parameter is deprecated. Use api_base_url instead.

Source code in nmdc_client/functional_annotation_agg_search.py

def __init__(self, api_base_url: str = API_BASE_URL, env: str = ""):
    super().__init__(
        api_base_url=api_base_url,
        env=env,
    )

CollectionSearch Subclasses¶

Choosing a Subclass¶

Biosample and Study Related¶

BiosampleSearch ¶

StudySearch ¶

CollectingBiosamplesFromSiteSearch ¶

FieldResearchSiteSearch ¶

Sample Processing Related¶

ProcessedSampleSearch ¶

MaterialProcessingSearch ¶

StorageProcessSearch ¶

Data Generation Related¶

DataGenerationSearch ¶

ManifestSearch ¶

InstrumentSearch ¶

ConfigurationSearch ¶

Data and Processing Related¶

WorkflowExecutionSearch ¶

CalibrationSearch ¶

DataObjectSearch ¶

get_data_objects_for_studies ¶

get_data_objects_for_study ¶

FunctionalAnnotationAggSearch ¶

`CollectionSearch` Subclasses¶