Catalog Query API¶

Catalogs feature an NDN name-based query API to enable discovery.

Query Request¶

Catalog queries are expressed as a JSON Interest name component:

/<prefix>/query/<query-parameters>

Query parameters simultaneously support two types of queries:

1. component type-based
2. absolute prefix-based

The requestor will encode query parameters as a JSON object, with the format: {[field1]=[search1],[field2]=[search2],?=[search3]} where field1 and field2 are Name components. ? indicates an absolute prefix-based autocomplete search where search3 is the prefix. (See Schema)

Query Parameters Schema¶

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "catalog query",
    "type": "object",
    "items": {
        "title": "query parameters",
        "type": "object",
        "properties": {
            "name": {
                "type": "string"
            },
            "activity": {
                "type": "string"
            },
            "product": {
                "type": "string"
            },
            "organization": {
                "type": "string"
            },
            "model": {
                "type": "string"
            },
            "experiment": {
                "type": "string"
            },
            "frequency": {
                "type": "string"
            },
            "modeling realm": {
                "type": "string"
            },
            "variable name": {
                "type": "string"
            },
            "ensemble member": {
                "type": "string"
            },
            "ensemble": {
                "type": "string"
            },
            "sample granularity": {
                "type": "string"
            },
            "start time": {
                "type": "string"
            },
            "field campaign": {
                "type": "string"
            },
            "optical properties for radiation": {
                "type": "string"
            },
            "grid resolution": {
                "type": "string"
            },
            "output type": {
                "type": "string"
            },
            "timestamp": {
                "type": "string"
            },
            "?": {
                "description": "Autocomplete search field"
                "type": "string"
            },
            "??": {
                "description": "Prefix-based search"
                "type": "string"
            }
        },
        "required": []
    }
}

Query Results¶

Catalogs answer queries with one or more Query Result Data packets. Each packet contains a JSON list of matching NDN name URIs
Query responses are Data containing a JSON list of matching name URIs. Each packet is named according to:

/<prefix>/query-results/<catalog-id>/<query-parameters>/<version>/<segmentNumber>

The response set is versioned and uniquely identifies the catalog that produced it (e.g. identity key digest).

Query Results Data JSON¶

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Catalog Query Result",
    "type": "array",
    "items": {
        "title": "QueryResults",
        "type": "object",
        "properties": {
            "resultCount": {
               "description": "The total number of the records in query results"
               "type": unsigned integer
            },
            "results": {
               "description": "List of NDN name URIs"
               "type": Array
            },
            "next": {
                "description": "Autocomplete search potential next field(s)"
                "type": Array
            }
        },
        "required": [resultCount]
    },

}