Skip to main content

Programmatic Map Selections

The Atlas interface provides various selections (filters) you may want to apply to your map, including semantic search and text search on your uploaded data columns.

This capability can also be leveraged programmatically through our query endpoints.

See the API Reference for more details.

Querying with selections​

In this section, we cover several examples of different selections you can programmatically query. All queries are built off the domain specific language (DSL) we use for Atlas operations such as tagging. The endpoints will output a JSON list of data point ids that match your query.

Search Query​

You can search for any keyword over any column in your dataset by performing the below query:

import requests
import json

# Query endpoint
url = "https://api-atlas.nomic.ai/v1/query"

# Request payload
payload = {
    "projection_id": "d50b79ea-910d-4975-9930-b5ce0736fbd0",
    "selection": {
        "method": "composition",
        "conjunctor": "ALL",
        "filters": [
            {
                "method": "search",
                "query": "New York",
                "field": "text",
            }
        ]
    }
}

# Set the headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <Your API Key>"
}

# Send the POST request
response = requests.post(url, data=json.dumps(payload), headers=headers)

Inverting Filters​

You can invert your filter (e.g. returning all documents that do not contain a certain keyword) by setting polarity to false.

# Request payload
payload = {
    "projection_id": "d50b79ea-910d-4975-9930-b5ce0736fbd0",
    "selection": {
        "method": "composition",
        "conjunctor": "ALL",
        "filters": [
            {   
                "polarity": False,
                "method": "search",
                "query": "New York",
                "field": "text",
            }
        ]
    }
}

Composing Filters​

You can combine different filters as shown below. Atlas supports two operations for composing filters: ANY will return results that match at least one of the filters, ALL will return results that exactly match all the filters.

import requests
import json

# Query endpoint
url = "https://api-atlas.nomic.ai/v1/query"

# Request payload
payload = {
    "projection_id": "d50b79ea-910d-4975-9930-b5ce0736fbd0",
    "selection": {
        "method": "composition",
        "conjunctor": "ALL",
        "filters": [
            {
                "method": "search",
                "query": "New York",
                "field": "text",
            },
            {
                "method": "search",
                "query": "Stock Market",
                "field": "text",
            }
        ]
    }
}

# Set the headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <Your API Key>"
}

# Send the POST request
response = requests.post(url, data=json.dumps(payload), headers=headers)

Use the KNN (topk) endpoint to return a sorted list of the top most semantically similar results to your query with an optional selection attached. The selection is applied first to your data points, and the top K nearest neighbors are then fetched from the filtered results. Note, that this is not the same as composing filters with a semantic search filter.

import requests
import json

# Top K endpoint
url = "https://api-atlas.nomic.ai/v1/query/topk"

# Request payload
payload = {
    "projection_id": "d50b79ea-910d-4975-9930-b5ce0736fbd0",
    "k": 50,
    "query": "new york stock market",
    "selection": {
        "polarity": True,
        "method": "composition",
        "conjunctor": "ALL",
        "filters": [
            {
                "method": "search",
                "query": "New York",
                "field": "text",
            }
        ]
    }
}

# Set the headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <Your API Key>"
}

# Send the POST request
response = requests.post(url, data=json.dumps(payload), headers=headers)