Attention

The search interface for Citrination is powerful but complex. This guide is still a work in progress.

Search Client Examples

The SearchClient class allows you to run search queries against Citrination. The search client utilizes a deeply recursive query structure that enables complex sets of criteria to be applied.

For more detailed information about the structure of search queries, consult the documentation found here: (https://citrineinformatics.github.io/api-documentation/#tag/search

Basic Usage

You may execute search queries which return individual records (equivalent to running search from the landing page on Citrination), or datasets by using the pif_search or dataset_search methods on the SearchClient respectively.

# ... client initialization left out

search_client = client.search

# Construct a query which returns records in dataset 1160
# and have chemical formulas matching CoSi
query = PifSystemReturningQuery(
            query=DataQuery(
                dataset=DatasetQuery(
                    id=Filter(equal='1160')
                ),
                system=PifSystemQuery(
                    chemical_formula=ChemicalFieldQuery(
                        filter=ChemicalFilter(
                            equal='CoSi')))))

# Execute the search (we use pif_search because we have a PifSystemReturningQuery)
results = search_client.pif_search(query)

# Get the ID of the first hit
record_id = results.hits[0].id

# ... client initialization left out

search_client = client.search

# Construct a query which returns datasets
# which contain records with chemical formulas
# matching MgO2
query = DatasetReturningQuery(
            query=DataQuery(
                system=PifSystemQuery(
                    chemical_formula=ChemicalFieldQuery(
                        filter=ChemicalFilter(
                            equal='MgO2')))))

# Execute the search; we use dataset_search because
# we have a DatasetReturningQuery
results = search_client.dataset_search(query)

# The resulting hits represent datasets which
# contain records that matched our criteria
print(results.hits[0].name)
# => Wikipedia

print(results.hits[0].id)
# => 114201

Note that dataset_search does not return the contents of the datasets, but instead returns the metadata for datasets whose contents match the criteria applied by your search. In other words, if you pass a query to dataset_search which applies the criteria that matching records must contain a property called “Property Band gap”, the resulting hits will be datasets which contain records satisfying that criteria.

Simple Query Generation

The search client provides a method called generate_simple_chemical_query which simplifies the interface for creating a new query. If you only need to apply a simple set of constraints, this can be a quick way to generate a query.

# ... client initialization left out

search_client = client.search

# Construct a query which returns records in dataset 1160
# which have GaN as a chemical formula and have band gap
# property values between 1.5 and 1.6
query = search_client.generate_simple_chemical_query(chemical_formula="GaN",
                                                     property_name="Band gap",
                                                     property_min=1.5,
                                                     property_max=1.6)

results = search_client.pif_search(query)

# Get the ID of the first hit
record_id = results.hits[0].id
print(results.hits[0].extracted)
# => {
#   u'property_units': u'eV',
#   u'property_value': u'1.57',
#   u'chemical_formula': u'GaN',
#   u'property_name': u'Band gap',
#   u'reference_doi': u'10.1038/s41524-017-0013-3'
# }