Domain specific language query

This section describes how to access data in Helix Search using the Domain Specific Language (DSL). All users, admins, and super users can perform search using a DSL query.

You must use the DSL keywords in conjunction with Boolean queries to perform complex searches in Helix Search.

DSL keywords

Here is a list of all the DSL keywords that you can use to perform a search. The DSL keywords must be used in conjunction with the Boolean queries.

Keyword Description Query type Example

model

Specify the data model you want to search for. See Data model.

term

model: content

depotFile

Specify the depot path using a wildcard character '*'. If you have special characters in your depot path then you can use double quotes in the DSL query.

wildcard

depotFile: //depot/main/*

depotFile: "//depot/- 200/tests/*"

tags

Specify the detected AI (Artificial Intelligence) tags.

list of match

tags: tree rock

ext

Specify the file extension or the file name.

list of wildcard

ext: jpeg png

description

Specify the changelist description within quotes.

match_phrase_prefix

description: "fixed a bug"

date

Specify a date range.

range

date: 2020/9/19 2023/2/22:23:59:59

size

Specify the file size. Accepts values in KB or KiB up to EiB.

range

size: 3MB 8MB

user

Specify the user name.

term

user: axyz

rev

Specify the revision range or use 'latest'.

range

rev: latest

change

Specify the changelist range or use 'latest'.

range

change: 10223 10230

content

Specify the content of a file to match a query.

match_phrase_prefix

content: "fixed bug"

Boolean queries

Query Description Bool type Example

MUST +

Specify the term that must exist in the search results.

must

MUST user: axyz

Returns all the files in the results where the user name matches 'axyz'.

NOT -

Specify the term that must not be included in the search results.

must_not

-depotFile: //depot/test/*

Returns files from all depot paths except for '//depot/test/'

<empty>

Specify one term or another term that should be included in the search results.

should

tags: tree description: "Pine tree"

Returns all the files that have AI tags 'tree' or has 'Pine tree' in the description.

Usage examples

This section outlines a few DSL example queries run from the Helix Search web UI.

Sample DSL query 1

MUST model: asset tags: tree rock -depotFile: "//depot/- 200/tests/*" +user: axyz

This DSL query will perform a search and get results for all the files in Helix Search that match the following criteria:

  • the data model type is 'asset'

  • the search matches the AI tags 'tree' or 'rock'

  • excludes all files in the depot file path '//depot/tests/'

  • and matches the user name 'axyz' only

Sample DSL query 2

+date: 2022/7/26 2022/8/1 +model: asset

This DSL query will preform a search and get results for all the assets that were submitted in the specified date range.

Sample DSL query 3

ext: fbx obj MUST tags: white light MUST size: 3MB 100MB +model: asset

This DSL query will preform a search and get results for all the files in Helix Search that match the following criteria:

  • the file extension can be fbx or obj

  • the AI tags in a file must contain both the tags 'white' and 'light'

  • the file size must be between 3MB and 100MB

  • the data model type must be an 'asset'

Sample DSL query 4

MUST ext: fbx obj MUST size: 3MB 100MB

This DSL query will preform a search and get results for all the files in Helix Search that match the following criteria:

  • the file extension can either be fbx or obj but not both, so this will not return any results

  • the file size must be between 3MB and 100MB

DSL query endpoint

Summary

Execute a DSL query.

GET api/v1.3/search/dsl

Description

Execute a DSL query to perform a search.

Parameters

Parameter Description Type

search

The Helix Search DSL query URL encoded.

string

from

The pagination start position.

integer

size

The pagination size. For example, when set to 10, you will only see 10 results per page.

integer

Example usage

curl -X GET --location "http://localhost:1601/api/v1.3/search/dsl?search=ext%3A+mp3+wav+%2Bmodel%3A+asset"
-H "Authorization: Bearer <JWT>" \
-H "Content-Type: application/json"

Helix Search responds with:

{
  "took": 174,
  "timed_out": false,
  "_shards": {
    "failed": 0.0,
    "successful": 1.0,
    "total": 1.0,
    "skipped": 0.0
  },
  "hits": {
    "total": {
      "relation": "eq",
      "value": 847
    },
    "hits": [
      {
        "_index": "perforce1",
        "_id": "change-917081",
        "_score": null,
        "_source": {
        "type": "change",
        "change": 917081,
        "date": 1179756208000,
        "client": "tony-barney-dev",
        "user": "tony",
        "restricted": false,
        "description": "Add P4Perl 3.5943 sources to depot as basis for the first
                        productized version of P4Perl.
        "depotFile": "//depot/main/p4-perl/...",
        "indexDate": 0
      },
      "sort": [ 
        -9223372036854775808
      ]
     }, ......    ],
   "max_score": null
  },
  "terminated_early": false
}

If a request fails

<error code>:

  • 400 DSL parsing error or Elastic bad requests

  • 401 Unauthorized

For more information about the DSL API endpoint, see Access the Swagger REST API .