SDTF Query Language

SDTF Query Langage format API reference

The SDTF Query Language is a JSON structure describing several match criteria used to select nodes - tokens, groups and collections - within the token tree.

Examples

Get a collection exactly named "Colors" and all its children of kind: "token"

{
  "where": {
    "collection": "^Colors$",
    "select": {
      "collection": true,
      "children": {
        "tokens": true
      }
    }
  }
}

Query Language Structure

Every SDTFQuery holds a single a where property being:

  • an object: to select one branch of the graph

  • an array of objects: to select many branches of the graph - equivalent to an OR statement.

type SDTFQuery = { where: Where | Array<Where> }

The where property splits in 3 kinds: token, group, collection - offering a dedicated set of options to match against the given kind.

Where Token

type WhereToken = {
  token:
    | string // regex compatible
    | {
        name?: string; // regex compatible
        description?: string; // regex compatible
      };
  select:
    | true
    | {
        token?: boolean;
        parents?:
          | true
          | {
              groups?: true;
              collections?: true;
            };
      };
};

Where Group

type WhereGroup = {
  group:
    | string // regex compatible
    | {
        name?: string; // regex compatible
        description?: string; // regex compatible
      };
  select:
    | true
    | {
        group?: boolean;
        parents?:
          | true
          | {
              groups?: true;
              collections?: true;
            };
        children:
          | true
          | {
              groups?: true;
              collections?: true;
              tokens?: true;
            };
      };
};

Where Collection

type WhereCollection = {
  collection:
    | string // regex compatible
    | {
        name?: string; // regex compatible
        description?: string; // regex compatible
      };
  select:
    | true
    | {
        collection?: boolean;
        parents?:
          | true
          | {
              groups?: true;
            };
        children:
          | true
          | {
              groups?: true;
              tokens?: true;
            };
      };
};

Recursion

The where property can alternatively holds a andWhere property instead of the select property.

Doing so, the andWhere property can receive any where operator described earlier.

Note: since Collections cannot be nested, we cannot nest a andWhere Collection operator into another where or andWhere Collection

{
  "where": {
    "collection": "^colors$",
    "andWhere": {
      "group": "^base",
      "andWhere": {
        "token": ".*",
        "withTypes": { "include": ["color"] },
        "select": {
          "token": true,
          "parents": true
        }
      }
    }
  }
}

Query Result

Once executed by the engine, the query returns a QueryResult that helps to work with the matched tree nodes.

Last updated