GQL

GQL (Getvisibility Query Language) is a query language designed to enhance the flexibility and efficiency of querying data through the DSPM+, DDC, and EDC platforms. It enables the creation of custom queries without the need for hard coding, significantly simplifying the process of filtering through and analysing data.

Based on Apache Lucene query language, GQL supports boolean, term, and range queries. This flexibility allows the language to seamlessly integrate with the platform’s Analytics software to produce elegant and insightful visualisations.

Once mastered, GQL offers maximum flexibility, enabling both broad and precise data analysis.

Usage

Terms

There are separate sets of terms used for the different datasets within the DSPM+, DDC, and EDC platforms. Each of the datasets allow for unique GQL terms relating to this data:

• Files: Unstructured data discovered and classified on-prem and in the cloud file storage locations. GQL term examples: path, ingestedAt, flow

• Trustees: Users and groups that are discovered in on-prem and in cloud IAM systems. GQL term examples: type, isAdmin, outdatedPassword

• Activity: User activities tracked by the endpoint classification platform. GQL term examples: recipients, operation, agentId

• Management: Administrative data from individual classification endpoints. GQL term examples: lastSeen, status, os

• Remediation: Actions initiated by users to remediate issues. GQL term examples: actionType, errorReason, updatedPermissions

• Streaming: Real time events from DDR functionality. GQL term examples: source, eventTime, eventId

• Extended Streaming: Similar to Streaming but there is a longer delay as to when these events will appear in the UI. Some of the event types may also contain more detail than when compared to the Streaming dataset. GQL term examples: tenantId, rawEventType, streamingEventType

• File Audit Log: List of events that are associated with the scanning of files. GQL term examples: source, functionalityName, moduleName

For the full sets of terms, see tables below.

Operations

Operations are performed on or between terms to help filter data. The available operations are:

• AND Combines queries to match items meeting all conditions

• OR Matches items meeting any listed conditions

• () Groups queries to clarify operation order

• = Equal to

• != Not equal to

• > Greater than

• < Less than

• >= Greater than or equal to

• <= Less than or equal to

• EXISTS

• NOT_EXISTS

Formation

Queries are formed using terms, their values, and operations. They can be as simple as a query looking for High Risk HR Data:

dataAttributeName=HR AND risk=2

To complex queries specifying Health, Safety, and Compliance Documents as a data asset in DSPM:

complianceTag=PII AND dataAttributeName=HR AND (dataAttributeName=Record OR
dataAttributeName=Legal OR dataAttributeName=Safety) AND
(detectorHits="Health Insurance" OR detectorHits="Risk assessment" OR
detectorHits="Policy and Procedure" OR detectorHits="Compliance report" OR
detectorHits="Safety Policies" OR detectorHits="Security Policies")

The UI will give suggestions as you type to help out.

You should experiment with GQL queries across various platform interfaces. See what works and what doesn't. Get creative and let the real-time suggestions assist you. Remember, you can save the queries you create as bookmarks for future use.

Click on the star

Enter a description, select Accept

The bookmark is saved

Scroll down to see saved bookmarks

Dates

Queries can be created that incorporate dates. These can include exact dates and times or ranges. Date types include: createdAt, lastModifiedAt, and ingestedAt.

GQL will provide suggestions for common time intervals such as minutes, days, months, and years.

Once a date type has been selected and an operation associated with it, a date interface will be presented to the user. Simply search for and select the appropriate date to create the query.

Date ranges

If a specific range of dates are needed, for example, all files created in May 2022, the following method should be used.

This method will search for files whose creation dates are greater than or equal to midnight on the 1st May 2022 and less than midnight on the 1st of June 2022.

1. Type createdAt>= and select the first date

1. Select AND

1. Type createdAt< and select the closing date

1. Hit enter or the search icon and the query will the filter the results

This method can be used with any date data type. It can be as granular as seconds or as broad as years.

Aggregation

When creating or editing widgets such as counters, charts, or maps in the Analytics boards you will have the ability to aggregate some of the terms in the datasets. For example: you can use counts to show critical shared files, group by file type when displaying classification results, or use multiple groupings to create more complex visualisations.

While not strictly part of GQL yet, they are useful to know as it will help in constructing more descriptive visualisations.

GQL glossaries

• GQL Term: Used in the query

• Label: Displayed in the interface

• Type: Data type of the term

• Aggregation: Grouping types that are available to that term, only in the Analytics boards

Files Dataset

Unstructured data discovered and classified from on-prem and cloud file storage locations.

GQL Term	Label	Type	Description	Aggregation
fileId	Id	STRING	The internal Id of the document
fileType	File Type	STRING	The type of the document	Can be grouped
path	Path	STRING	The path of the document
contentLength	Content length	LONG	The size of the document in bytes	count, sum, average, min, max, median, Can be grouped
risk	Risk	NUMBER	The document risk factor. low=0, medium=1, high=2
source	Source	STRING	The source of the document	Can be grouped
createdAt	Created at	DATE	The document creation date	min, max, median, Can be grouped
lastModifiedAt	Last modified at	DATE	The document last modified date	min, max, median, Can be grouped
ingestedAt	Ingested at	DATE	The document ingested date	min, max, median, Can be grouped
lastAccessedAt	Last accessed date	DATE	The document last accessed date	min, max, median, Can be grouped
flow	Flow	STRING	The document current flow stage	Can be grouped
classification	Classification	STRING	The classification of the document	Can be grouped
classificationConfidence	Classification confidence	DOUBLE	The classification confidence of the document
configurationIds	Configuration Id	STRING	The configuration id of the document
connectorId	Connector name	STRING	Name of the scan connector	Can be grouped
sensitive	Scan Trigger	BOOLEAN	The document sensitive flag
scanTrigger	Manual Classification	BOOLEAN	The trigger of the file scanning
critical	Critical	BOOLEAN	The document critical flag
md5	Document hash	STRING	The hash value of the document	Can be grouped
keywordHits	Keyword Hits	STRING	The keyword hits of the document	Can be grouped
detectorHits	Detector Hits	STRING	The detector hits of the document	Can be grouped
directPermissionsId	Direct permissions ids	STRING	Direct permissions ids of the document	Can be grouped
indirectPermissionsId	Indirect Permission Id	STRING	(Experimental) The trustee Id of the document that has access either directly or indirectly
indirectPermissions	Indirect Permissions	STRING	(Experimental) The trustee name of the document that has access either directly or indirectly
trusteeName	Trustee Name	STRING	The name of an owner of the document	Can be grouped
trusteeLoginName	Trustee Login Name	STRING	The login name of the owner of the document
dataAttributeName	Data Attribute Name	STRING	The data attribute of the document	Can be grouped
distributionTags	Distribution Tag Name	STRING	The distribution tag of the document	Can be grouped
	Keyword	STRING	Keyword of the document	Can be grouped
complianceTag	Compliance Tag	STRING	Compliance Tag of the document	Can be grouped
location	Location	STRING	To get Documents by connection location	Can be grouped
language	Language	STRING	The document language
externalSharedLink	External Shared Link	BOOLEAN	The document sharing status
ownerId	Owner Identifier	STRING	The document owner identifier	Can be grouped
downloadUrl	Download URL	STRING	The download URL of the document
machineName	Machine Name	STRING	The machine name of the endpoint where the document originated	Can be grouped
cloudLabels	Cloud Labels	STRING	The document cloud labels	Can be grouped
dataAssets	Data asset	STRING	The document data asset	Can be grouped
departments	Department	STRING	The document department	Can be grouped
dataOwners	Data Owner	STRING	Data Owner Name	Can be grouped
dynamicAttributes	Dynamic attribute	STRING	The document dynamic attribute	Can be grouped
sourceEntityId	Source entity identifier	STRING	The document id as reported from the source system	Can be grouped

Trustees dataset

Users and groups that are discovered in on-prem and in cloud IAM systems

GQL Term	Label	Type	Description	Aggregation
trusteeId	Trustee ID	STRING	The Id of the trustee	Can be grouped
groups	Groups	STRING	The groups that the trustee is a member of	Can be grouped
type	Trustee Type	STRING	Indicates the trustee is a user or a group	Can be grouped
source	Source	STRING	The type of the connector	Can be grouped
name	Login Name	STRING	Login name of the trustee	Can be grouped
displayName	Display Name	STRING	The display name of the trustee (user or group)	Can be grouped
isEnabled	Enabled Status	BOOLEAN	Indicates if the trustee is enabled
isAdmin	Admin Privileges	BOOLEAN	Indicates if the trustee has administrator privileges
outdatedPassword	Outdated Password	BOOLEAN	Indicates if the trustee's password is outdated	min, max, median, Can be grouped
lastLoginAt	Last Login Date	DATE	The timestamp when the trustee (user or group) logged in	min, max, median, average, Can be grouped
lastModifiedAt	Last Modified Date	DATE	The timestamp when the trustee's (user or group) record was modified	min, max, median, average
createdAt	Creation Date	DATE	The time trustee was created	min, max, median, average
ingestedAt	Ingestion Date	DATE	The timestamp when the trustee (user or group) was ingested	min, max, median, Can be grouped
configurationId	Configuration ID	STRING	Configuration ID associated with the trustee (user or group)	Can be grouped
isActive	Active Status	BOOLEAN	Indicates if the trustee is active

Activity dataset

User activities tracked by endpoint classification.

GQL Term	Label	Type	Description	Aggregation
spanId	Span ID	STRING	The span ID of the activity performed	Can be grouped
traceId	Trace ID	STRING	The trace ID of the activity performed	Can be grouped
recipients	Email Recipients	STRING	The recipients of the email	Can be grouped
senderEmail	Email Sender	STRING	The sender of the email	Can be grouped
subject	Email Subject	STRING	The subject of the email	Can be grouped
operation	Operation Type	STRING	The type of the operation performed	Can be grouped
eventTime	Event Time	DATE	The time when the event occurred	min, max, median, Can be grouped
ipAddress	IP Address	STRING	The IP address of the machine where the activity was performed	Can be grouped
eventType	Event Type	STRING	The event type of the activity performed (i.e. Activity with File, Email)	Can be grouped
hostName	Host Name	STRING	The hostname of the machine where the activity was performed	Can be grouped
department	Department	STRING	The department of the user who performed the activity	Can be grouped
agentId	Agent Id	STRING	The identification of the agent who performed the activity	Can be grouped
entityId	Agent	STRING	Unique identifier of the machine	Can be grouped
user	User	STRING	The username of the individual who performed the activity	Can be grouped
contentLength	File Size	BYTES	The size of the file involved in the activity	sum, average, min, max, median, Can be grouped
mimeType	File Type	STRING	The MIME type of the file	Can be grouped
fileName	File Name	STRING	The name of the file	Can be grouped
filePath	File Path	STRING	The path of the file	Can be grouped
creationTime	Created At	DATE	The time when the file involved in the activity was created	min, max, median, Can be grouped
lastModificationTime	Last Modified At	DATE	The last time the file involved in the activity was changed	min, max, median, Can be grouped
tags	Tags	STRING	Classification tags	Can be grouped
classificationTag	Classification Tag	STRING	Classification Tag of the document	Can be grouped
distributionTag	Distribution Tag	STRING	The distribution tag of the document	Can be grouped
complianceTag	Compliance Tag	STRING	Compliance Tag of the document	Can be grouped
senderDomain	Sender Domain	STRING	Sender Domain of email	Can be grouped
recipientDomain	Recipient Domain	STRING	Recipient Domain of email	Can be grouped

Management dataset

Administrative data from individual classification endpoints

GQL Term	Label	Type	Description	Aggregation
lastSeen	Last Seen	DATE	The last time the device was observed to be online	min, max, median, Can be grouped
hostName	Host Name	STRING	The identification of the agent who performed the activity	Can be grouped
domain	Domain	STRING	Shows the Active Directory domain name, if applicable	Can be grouped
ipAddress	IP Address	STRING	Shows the IP address last recorded when the device was active	Can be grouped
status	Online Status	STRING	Shows whether the device is currently online or offline	Can be grouped
user	User Name	STRING	Displays the name of the last user who logged into the device	Can be grouped
version	Agent Version	STRING	The version of the agent software currently installed on the device	Can be grouped
os	OS	STRING	Indicates the operating system of the device, either Windows or Mac	Can be grouped
deviceId	Device ID	STRING	Displays the ID of the device
department	Department	STRING	Displays the department the agent belongs to	Can be grouped

Remediation Dataset

List of all remediation events initiated by users.

GQL Term	Label	Type	Description	Aggregation
source	Source connector type	STRING	Connector type of the source file	Can be grouped
status	Status	STRING	Status of the remediation request	Can be grouped
actionType	Action type	STRING	Action type	Can be grouped
errorReason	Error Reason	STRING	Error Reason	Can be grouped
updatedAt	Updated At	STRING	Modification date of the file	min, max, median, Can be grouped
updatedPermissions	Updated permission	STRING	Permissions that were revoked	Can be group
updatedTrustees	Updated trustees	STRING	Updated trustees	Can be grouped
createdAt	Created At	DATE	Creation date of remediation request	min, max, median, Can be grouped
path	Source file path	STRING	Path of the source file	Can be grouped
errorReasonFull	Full Error Reason	STRING	Full error reason message	Can be grouped
targetSource	Target connector type	STRING	Connector type of the target file	Can be grouped
targetPath	Target file path	STRING	Path of the target file	Can be grouped
createdBy	Created By - ID	STRING	ID of the user who initiated remediation	Can be grouped
createdByName	Created By - Username	STRING	Name of the user who initiated remediation	Can be grouped
fileId	File ID	STRING	The Id of the file	Can be grouped
configurationIds	Source configuration id	STRING	Configuration id of the source file	Can be grouped
batchRequestId	ID of a batch request	STRING	ID of a batch request related to the event	Can be grouped
targetConfigurationIds	Target configuration id	STRING	Configuration id of the target file	Can be grouped

Streaming Data Set

Real time events events from DDR

GQL Term	Label	Type	Description	Aggregation
source	Source	STRING	Source of the event	Can be grouped
eventType	Event type	STRING	Type of the event	Can be grouped
actionType	Action type	STRING	Type of the action	Can be grouped
eventTime	Event time	DATE	The time of the event	min, max, median, Can be grouped
userName	Username	STRING	Name of the user	Can be grouped
userId	User ID	STRING	Id of the user	Can be group
fileName	File name	STRING	File name	Can be grouped
eventId	Id	STRING	Id of a file	Can be grouped
path	File path	STRING	File path	Can be grouped
configurationIds	Scan configuration ID	STRING	Scan configuration ID	Can be grouped
fileId	fileId	STRING	Id of the file	Can be grouped

Extending Streaming

Similar to Streaming events dataset but usually with more detail, however the do not appear on the UI as quickly.

GQL Term	Label	Type	Description	Aggregation
id	ID	STRING	The unique identifier of the streaming event	Can be grouped
tenantId	Tenant ID	STRING	The identifier of the tenant	Can be grouped
scanConfigurationId	Scan Configuration ID	STRING	The identifier of the scan configuration	Can be grouped
rawEventType	Raw Event Type	STRING	The type of the raw event	Can be grouped
streamingEventType	Streaming Event Type	STRING	The type of the streaming event	Can be grouped
actionType	Action Type	STRING	The type of action performed	Can be group
entityId	Entity ID	STRING	The identifier of the entity	Can be grouped
entityName	Entity Name	STRING	The name of the entity	Can be grouped
fileId	File ID	STRING	The identifier of the file	Can be grouped
sourcePath	Source Path	STRING	The source path of the file
path	Path	STRING	The path of the file
connectorType	Connector Type	STRING	The type of connector used	Can be grouped
userId	User ID	STRING	The identifier of the user	Can be grouped
userName	User Name	STRING	The name of the user	Can be grouped
timestamp	Timestamp	DATE	The time when the event occurred	min, max, median, Can be grouped

File Audit Log

Events associated with scanning of files.

GQL Term	Label	Type	Description	Aggregation
source	Source connector type	STRING	Connector type associated with the file	Can be grouped
eventType	Event Type	STRING	Type of the event	Can be grouped
functionalityName	Functionality Name	STRING	The name of the functionality associated with the event	Can be grouped
moduleName	Module Name	STRING	Name of the module associated with the event	Can be grouped
createdAt	Created At	STRING	Creation date of the file	min, max, median, Can be grouped
message	Message	STRING	Message	Can be group
path	File path	STRING	Path of the file	Can be grouped
fileId	File ID	STRING	The Id of the file associated with the event	Can be grouped
scanId	Scan ID	STRING	Id of the scan associated with the event	Can be grouped
configurationId	Configuration ID	STRING	ID of the configuration associated with the event	Can be grouped