Page tree
Skip to end of metadata
Go to start of metadata


Query transformers modify a QueryRequest message on its way to the index engine. The default AIE query transformers make the incoming query compatible with the index records through tokenization, stopword removal, spellchecking, synonym expansion and similar linguistic transformations. Custom transformers usually augment or refine the query in some way.

This page demonstrates how to create and run a very simple query transformer. Once you see it run, you can concentrate on making the modifications that suit your project. 


Related Pages

The following pages contain information that is especially relevant to this topic.


View incoming links.

Creating Custom Code

This section demonstrates how to implement a simple query transformer in Java, and how to insert it into a query workflow.

Create a Custom Query Transformer in Java

When you use AIE Designer to create a project, one of the options is to include sample code.  If you use that option, Designer adds several Java files to the project, one of which is  The example on this page (ExampleQueryTransformer) was modified from that file. You can download the modified file here.

Imported Classes

The following query transformer code uses these packages and classes.

Based on
package com.acme.examples;

import java.util.ArrayList;
import java.util.List;

import com.attivio.sdk.AttivioException;
import com.attivio.sdk.server.annotation.ConfigurationOption;
import com.attivio.sdk.server.component.query.QueryTransformer;


Query transformers that extend QueryTransformer must implement a single method called processQuery():

Based on
/** Sample query transformers that adds a new field for faceting. */
public class ExampleQueryTransformer implements QueryTransformer {
    private String facetField = "country";
    public List<QueryFeedback> processQuery(QueryRequest query) throws AttivioException {

Inside the processQuery method any business logic required can be performed, including changing the query, adding filters, removing filters, adding facets, etc. In this example, we have caught the incoming query and added a facet field to it.  See QueryRequest  for a long list of useful query-modification methods. Also see the adjacent page on Query Modification for examples.

Query Feedback

If desired a List of  QueryFeedback  objects can be appended to the QueryResponse object, so that a front-end developer can display those messages to the user or use the information to make decisions about how to display the results of the query, as shown here:

Based on
    // adding feedback is optional but is useful for letting end users know what happened.  
    List<QueryFeedback> feedback = new ArrayList<QueryFeedback>();
    feedback.add(new QueryFeedback(this.getClass().getSimpleName(), "sample", "Added a facet field: " + facetField));
    return feedback;

The feedback message contains the name of the query transformer, a name for the message ("sample" in this case), and the message itself.  There is also possible to send a list of parameters if necessary. 

This is a feedback message as it appears in the Legacy XML Response of the DebugSearch page:

Feedback section of an XML ResponseDocument
<queryFeedback name="sample" stage="SampleQueryTransformer">
   <message>Added a facet field: source_s</message> 

The feedback messages can be viewed from the search client application by extracting the QueryFeedback   object from the QueryResponse.  This is an example of extracting feedback messages from a response:

Feedback section of a Search Client
     for (QueryFeedback feedback : response.getFeedback()) {
      // Display feedback
      System.out.println("  Stage: " + feedback.getStageName());
      System.out.println("  Message Name: " + feedback.getMessageName());
      System.out.println("  Message: " + feedback.getMessage());

Get and Put Methods

In this example, we'll want to set the the source_s property dynamically from the AIE Administrator.  For that, we'll need two methods and an annotation.

Based on
@ConfigurationOption(displayName = "Facet Field", description = "Field to add a facet request for to each query request")
    public String getFacetField() {
        return facetField;
    public void setFacetField(String facetField) {
        this.facetField = facetField;


Configure a Component and Workflow

To use your new query transformer in AIE, you need to instantiate the class as a component, and then insert the component in a query workflow.

  1. Edit the java file in AIE Designer, adding it to your custom package (com.acme.examples in this example).  
  2. Save the file. AIE Designer's default behavior is to recompile the <project-name>.jar file when you save. (If you have changed this default, be sure to compile manually.)
  3. In the  AIE Runtime  menu,  Start All Project Servers.
  4. Deploy the jar file to the configuration servers.  For this step use the AIE Runtime menu Deploy Project Configuration command. (This step occurs automatically the very first time you start the project servers.)
  5. Use the AIE Runtime menu and View All Project Servers. Right-click on a running node.  Select View AIE Administrator.
  6. In AIE Administrator, navigate to System Management > Palette.
  7. Select New > Query Transformers > ExampleQueryTransformer (or use the name of your own custom transformer class).
  8. Give the new component a name, such as "myExampleQueryTransformer."  You can set the Facet Field on the "Other" tab, or leave it blank to accept the default from the java file. (Remember that a field must be "facetable" in the AIE Schema or this setting will have no effect.) Save the component.
  9. In AIE Administrator, navigate to System Management > Workflows > Query > defaultQuery.
  10. On the defaultQuery workflow editor, click the Add Existing Component button.  Select your new component (myExampleQueryTransformer).
  11. Use the Move Up button to position the new component just after the queryAttivioLinguistics subflow.  Save the workflow.
  12. You now have customized files in the project source area, and also dynamic files on the configuration server.  To collapse these changes into a single set of source files, perform the following two steps:
    1. In AIE Designer, in the AIE Runtime menu, select Update Local Configuration.  This copies your dynamic changes to your project's source area.
    2. In AIE Designer, In the AIE Runtime menu, select Deploy Project Configuration.  Use the Ignore Changes and Replace Existing Project option.  This wipes out your former dynamic changes and replaces them with equivalent files from the project source area. 
  13. Run a connector to ingest data.
  14. Look for a new facet in your search output, either in the Debug Search page or in SAIL.

Note that this transformer lets you dynamically explore facets based on various fields in your data.  Just edit the transformer in the AIE Administrator to change the field that the facet is based on.  For the "country" facet used as a default example on this page, the editor displays the default value:

and SAIL displays a new facet.  This one lists the country options when you load the Factbook cities feed:





  • No labels