QueryService provides methods to create, execute, validate, and count query requests.

For example, imagine a simple VQL query to return the name and ID of all documents where the product is Cholecap.

SELECT name__v, id
FROM documents
WHERE product__v = '00P000000000119'

The example below creates a new instance of QueryService called queryService, then uses the Query Builder to create the same query as shown above.

QueryService queryService = ServiceLocator.locate(QueryService.class);
Query myQuery= queryService.newQueryBuilder()
.withSelect(VaultCollections.asList("name__v", "id"))
.withFrom("documents")
.withWhere("product__v = '00P000000000119'")
.build();

Other interfaces in the query package also provide builders that you can use with a defined query. You can use QueryExecutonRequest to execute the query, QueryValidationRequest to validate the query, or QueryCountRequest to retrieve the total number of records the query returns without a full query execution.

Use QueryOperation to execute a query and to specify success and error handlers. Vault returns query results as instances of QueryExecutionResponse. You can retrieve individual field values using QueryExecutionResult.getValue(). When querying formula fields, Vault returns the value of the field after running the formula expression, not the expression itself.

Using Tokens in a Query

You can include Custom tokens and Vault tokens in queries.

QueryCountRequest.Builder, QueryExecutionRequest.Builder, and QueryValidationRequest.Builder provide withTokenRequest() methods which accept a TokenRequest and a QueryEscapeOverride. If you omit overrides, Vault escapes all Strings.

The following example uses the Query Builder to create a query containing two custom tokens, status_list and approved_date. It defines these tokens using the Token Request Builder to create a TokenRequest. Finally, it uses the Query Execution Request Builder to include both the Query and Token requests in a QueryExecutionRequest.

Query query = queryService.newQueryBuilder()
      .withSelect(asList("id"))
      .withFrom("documents")
      .withWhere("TONAME(status__v) CONTAINS (${Custom.status_list})")
      .appendWhere(QueryLogicalOperator.AND,
            "approved_date__c > ${Custom.approved_date}")
      .withMaxRows(50)
      .withOrderBy(asList("name__v"))
      .build();

TokenService tokenService = ServiceLocator.locate(TokenService.class);
TokenRequest tokenRequest = tokenService.newTokenRequestBuilder()
      .withValue("Custom.approved_date", LocalDate.now().minusDays(7))
      .withValue("Custom.status_list", asList("final__c","approved__c"))
      .build();

QueryExecutionRequest queryRequest = queryService
      .newQueryExecutionRequestBuilder()
      .withQuery(query)
      .withTokenRequest(tokenRequest)
      .build();

Vault resolves tokens in query responses, but not in error responses or when retrieving query strings with Query#getQueryString().

The following limitations apply:

You cannot reference System-managed Vault tokens in custom code.
Vault does not support tokens in queries using deprecated SDK interfaces.
Custom tokens must be formatted ${Custom.my_token__c}.
Vault tokens must be formatted ${Vault.my_token__c}.

Learn more in the Javadocs.

Using Record Properties

Record properties provide more information about a record than a query response normally provides. For example, you can retrieve a List of editable fields or the target of a hyperlink in a formula field.

You can request record properties using the QueryExecutionRequest#withQueryRecordPropertyTypes method, which accepts a List of QueryRecordPropertyType values. For example, the HIDDEN type provides a List of fields that are hidden due to Atomic Security, and the RECORD_PERMISSIONS type provides the Edit, Delete, Create, and Read permissions for the record.

Each property type has its own response object containing additional data about a record and methods to retrieve that data. For example, the QueryRedactedFieldResult response object for the REDACTED type provides the #getFieldNames() method to retrieve the names of redacted fields.

The following example uses QueryService and LogService to log record properties for my_object__c. The QueryHiddenFieldResult#getFieldNames() method checks whether possible_hidden_field__c is hidden. The QueryWeblinkResult#getWeblinks() method retrieves the target attribute for Link formula field my_weblink__c.

LogService logService = ServiceLocator.locate(LogService.class);
QueryService queryService = ServiceLocator.locate(QueryService.class);

QueryExecutionRequest request = queryService
    .newQueryExecutionRequestBuilder()
    .withQueryString("SELECT id, possible_hidden_field__c, my_weblink__c FROM my_object__c")
    .withQueryRecordPropertyTypes(VaultCollections.asList(QueryRecordPropertyType.HIDDEN, QueryRecordPropertyType.WEB_LINK))
    .build();

queryService.query(request)
    .onSuccess(response -> {
        response.streamResults().forEach(row -> {
            String id = row.getValue("id", ValueType.STRING);
            boolean fieldIsHidden = row
                .getTypedQueryRecordProperty(QueryHiddenFields.class)
                .getFieldNames()
                .contains("possible_hidden_field__c");

            QueryWebLinkTarget webLinkTarget = row
                .getTypedQueryRecordProperty(QueryWeblinkFields)
                .getWeblinks()
                .stream()
                .filter(w -> "my_weblink__c".equals(w.getFieldName()))
                .findFirst()
                .map(QueryWeblinkResult::getTarget).orElse(null);

            logService.info(String.format("Record: [%s], hidden: [%s], web link target: [%s]", id, fieldIsHidden, webLinkTarget));
        });
    })
    .onError(error -> {
        logService.error(error.getMessage());
    }).execute();

Learn more in the Javadocs.

Token Service

TokenService provides methods to define and resolve Custom tokens. You can use these tokens with:

HttpService to reference tokens in the URL of an External Connection record.
QueryService to reference tokens in a VQL query.
QueueService to reference tokens in Spark messages.

You can define custom tokens using TokenRequest.Builder as shown in the example below.

TokenService tokenService = ServiceLocator.locate(TokenService.class);
      TokenRequest.Builder builder = tokenService.newTokenRequestBuilder();

      builder.withValue("Custom.api_version", "1.0");
      builder.withValue("Custom.is_case_sensitive", Boolean.TRUE);
      builder.withValue("Custom.max_amount", new BigDecimal(100));

      TokenRequest tokenRequest = builder.build();

TokenService can only be used for Custom tokens. For Authorization tokens and Session tokens, use HttpService. For Vault tokens, use HttpService, QueryService, or QueueService.

Query Service

Using Tokens in a Query

Using Record Properties

Token Service