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 |
|
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 .