Querying a SDTF graph

Learn more about how to query your SDTF token graph.

Introduction

Your token system can be more complex than it seems. You will often need to interact with your token graph to transform a specific set of design tokens within a Specify configuration.

This article will help you understand how you can query your token graph to select a specific set of tokens.

Compatible parsers

You'll need to query your graph when using the following parsers:

• filter

• change-case

• convert-color

• convert-dimension

Query structure

Every Query holds a single a where property being an object, to select one branch of the graph, or an array of objects, to select many branches of the graph (OR statement).

Type Query = { 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.

The name property accepts a RegExp for a value. These resources will help you debug your regular expressions:

• https://regex101.com/
• https://regexr.com/

Where Token

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

Where Group

type WhereGroup = {
  group: string;
  select: 
    | true
    | {
      group?: boolean;
      parents?:
        | true
        | {
          groups?: true;
          collections?: true;
        }
      children:
        | true
        | {
          groups?: true;
          collections?: true;
          tokens?: true;
        }
    }
}

Where Collection

type WhereCollection = {
  collection: string;
  select: 
    | true
    | {
      collection?: boolean;
      parents?:
        | true
        | {
          groups?: true;
        }
      children:
        | true
        | {
          groups?: true;
          tokens?: true;
        }
    }
}

Use cases

Select tokens from a specific collection

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from collection named 'Colors'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "^Colors$",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Select tokens from several collections matching a naming pattern

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from all collections whose names contain 'colors'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "where": {
              "collection": "colors",
              "select": {
                "collection": true,
                "children": {
                  "tokens": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Select tokens from a specific group

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from all groups named 'brand'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "group": "^brand$",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Select tokens of a specific type from a collection

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get color tokens from the 'Android' collection",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "where": {
              "collection": "^Android$",
              "andWhere": {
                "token": ".*",
                "withTypes": { "include": ["color"] },
                "select": {
                  "token": true,
                  "parents": {
                    "collections": true
                  }
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Select all tokens from a collection and from groups matching a naming pattern

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get color tokens from the 'Android' collection and from all groups named 'components'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "where": {
              "collection": "^Android$",
              "andWhere": {
                "group": "^components$",
                "andWhere": {
                  "token": ".*",
                  "withTypes": {
                    "include": ["color"]
                  },
                  "select": {
                    "token": true,
                    "parents": true
                  }
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Select tokens from several groups with different names

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from the group named 'Components' and/or from the group named 'Semantic'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "where": {
              "collection": "^Android$",
              "andWhere": {
                "group": "^Components$|^Semantic$",
                "andWhere": {
                  "token": ".*",
                  "select": {
                    "token": true,
                    "parents": true
                  }
                }
              }
            }
          }
        }
      ]
    }
  ]
}