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

Collection and tokens

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

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

Tokens by type

Select all tokens of type: "color". See all available types in Supported types.

{
  "where": {
    "token": ".*",
    "withTypes": { "include": ["color"] },
    "select": true
  }
}

Tokens in a particular location

Select the tokens of type: "color", only within a group named "components" nested in a collection named "Colors".

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

Notice it also selects the containing "components" group and "Colors" collection thanks to select.parents: 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;
        };
    };
  withTypes?: {
    include?: Array<TokenTypeName>;
    exclude?: Array<TokenTypeName>;
  };
  withModes?: {
    include?: Array<string>;
    exclude?: Array<string>;
  }
};

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;
        };
    };
  withModes?: {
    include?: Array<string>;
    exclude?: Array<string>;
  }
};

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.