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.
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 SampleQueryTransformer.java. The example on this page (ExampleQueryTransformer) was modified from that file. You can download the modified file here.
The following query transformer code uses these packages and classes.
Query transformers that extend QueryTransformer must implement a single method called processQuery():
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.
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:
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:
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:
Get and Put Methods
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.
- Edit the java file in AIE Designer, adding it to your custom package (com.acme.examples in this example).
- 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.)
- In the AIE Runtime menu, Start All Project Servers.
- 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.)
- Use the AIE Runtime menu and View All Project Servers. Right-click on a running node. Select View AIE Administrator.
- In AIE Administrator, navigate to System Management > Palette.
- Select New > Query Transformers > ExampleQueryTransformer (or use the name of your own custom transformer class).
- 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.
- In AIE Administrator, navigate to System Management > Workflows > Query > defaultQuery.
- On the defaultQuery workflow editor, click the Add Existing Component button. Select your new component (myExampleQueryTransformer).
- Use the Move Up button to position the new component just after the queryAttivioLinguistics subflow. Save the workflow.
- 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:
- In AIE Designer, in the AIE Runtime menu, select Update Local Configuration. This copies your dynamic changes to your project's source area.
- 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.
- Run a connector to ingest data.
- 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: