GQL

GQL (Getvisibility Query Language) is a query language designed to enhance the flexibility and efficiency of querying data through the Forcepoint DSPM platform. It enables users to craft custom queries without the need for hard coding, significantly simplifying the process of filtering through and analyzing data.

Based on Apache Lucene query language, GQL supports boolean, term, and range queries. This flexibility allows the language to seamlessly integrate with the Forcepoint DSPM platform’s Analytics software to produce elegant and insightful visualizations. Once mastered, GQL offers maximum flexibility, enabling both broad and precise data analysis. This adaptability ensures that users can leverage the full potential of the Forcepoint DSPM solution, whether they are conducting comprehensive overviews or detailed investigations.

Usage

Terms

There are separate sets of terms used for the different data sets within the Forcepoint DSPM platform. Each of the data sets 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

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 Forcepoint 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 does not. Get creative and let the real-time suggestions assist you. Remember, you can save the queries you create as bookmarks for future use.

Select the star.

Enter a description, select Accept.

The bookmark is saved.

Scroll down to see all of your 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 Feb 2025, the following method should be used.

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

  1. Type createdAt>= and select the first date.

  2. Select AND.

  3. Type createdAt< and select the closing date.

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

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

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 on-prem and in the cloud file storage locations.

Table 1.
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  
modelVersion Version STRING    
contentLength Content length BYTES 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

  
category Category STRING The ML category of the document Can be grouped
categoryConfidence Category confidence DOUBLE The ML category confidence of the document  
subCategory Subcategory STRING The ML subcategory of the document  
subCategoryConfidence Subcategory confidence DOUBLE The ML subcategory confidence of the document  
source Source STRING The source of the document Can be grouped
createdAt Created at DATE The document creation date min, max

Can be grouped
lastModifiedAt Last modified at DATE The document last modified date min, max

Can be grouped
ingestedAt Ingested at DATE Data document passed through the ML pipeline min, max

Can be grouped
flow Flow STRING The document current flow stage in the ML pipeline. Classified, Catalogued, etc. Can be grouped
classification Classification STRING The ML classification of the document Can be grouped
classificationConfidence Classification confidence DOUBLE The ML classification confidence of the document  
configurationIds Configuration Id STRING The scan configuration id of the document  
connectorId Connector name STRING Name of the scan connector Can be grouped
classifierResult Classifier result NUMBER The classifier results of the document  
pii PII BOOLEAN The document PII flag  
piiConfidence PII confidence DOUBLE The PII confidence of the document  
pi PI BOOLEAN The document PI flag  
piConfidence PI confidence DOUBLE The PI confidence of the document  
sensitive Sensitive BOOLEAN The document sensitive flag  
manual Manual Classification BOOLEAN The flag for manually classified files  
critical Critical BOOLEAN The document critical flag  
modifiedAtMilli Last modified date milliseconds DATE The document last modified date in milliseconds  
createdAtMilli Created date milliseconds DATE The document created date in milliseconds  
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
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  
signatureConfidence Signature Confidence DOUBLE The signature confidence of the document  
dataAttributeName Data Attribute Name STRING The data attribute or ML Model hits of the document Can be grouped
distributionTag Distribution Tag Name STRING The distribution tag of the document Can be grouped
keyword 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 Can be grouped
externalSharedLink External Shared Link BOOLEAN The document sharing status Can be grouped
sourceSpecificLabelsA ttributes Source Specific Labels STRING The document source specific labels  
ownerId

Owner

Identifier

 STRING The document owner identifier Can be grouped

Trustees data set

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

Table 2.
GQL Term Label Type Description Aggregation
type type STRING User/Group Can be grouped
source source STRING The type of the connector Can be grouped
name name STRING Login name of the trustee Can be grouped
displayName displayName STRING Name of the trustee Can be grouped
isEnabled isEnabled BOOLEAN if the trustee is enabled  
isAdmin isAdmin BOOLEAN if trustee is an admin  
outdatedPassword outdatedPassword BOOLEAN The trustee has outdated password  
lastLoginAt lastLoginAt DATE The last time trustee logged in

min, max,

median, average

Can be grouped,

lastModifiedAt lastModifiedAt DATE The last time trustee was modified

min, max,

median, average
createdAt createdAt DATE The time trustee was created min, max, median, average
connectorId connectorId STRING Configuration Id of the trustee  
isActive isActive BOOLEAN if trustee is active  

Activity dataset

User activities tracked by the endpoint classification platform.

Table 3.
GQL Term Label Type Description Aggregation
recipients Email Recipients STRING The recipients of the email  
senderEmail Email Sender STRING The sender of the email  
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

Can be grouped
ipAddress IP Address STRING The IP address of the machine where the activity was performed Can be grouped
hostName Host Name STRING The identification of the agent who performed the activity Can be grouped
department Department STRING The department of the user who performed the activity Can be grouped
agentId Agent STRING Unique identifier of the machine  
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
creationTime Created At DATE The time when the file involved in the activity was created

min, max

Can be grouped
lastModificationTime Last Modified At DATE The last time the file involved in the activity was changed

min, max

Can be grouped
tags tags STRING Classification tags Can be grouped

Management data set

Administrative data from individual classification endpoints.

Table 4. Management data set
GQL Term Label Type Description Aggregation
lastSeen lastSeen DATE The last time the device was observed to be online

min, max

Can be grouped
hostName hostName 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 ipAddress STRING Shows the IP address last recorded when the device was active Can be grouped
status status STRING Shows whether the device is currently online or offline  
user user STRING Displays the name of the last user who logged into the device Can be grouped
version 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 deviceId 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.

Table 5. Remediation data set
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
createdAt 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

Table 6. Remediation data set
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
field fileld 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.

Table 7. Extending stream data set
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
scanConfigurat ionId 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.

Table 8. Extending stream data set
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
configurationld Configuration ID STRING ID of the configuration associated with the event Can be grouped