Elasticsearch QueryString Generator

Purpose and Scope

This document covers the QueryString generator, which produces query strings in Elasticsearch's Query String Query format from Galach syntax trees. The QueryString generator is one of three generator implementations in the Query Translator library, alongside the Native generator (see 5.1) and the Solr ExtendedDisMax generator (see 5.2).

For information about shared Lucene visitor components used by both QueryString and ExtendedDisMax generators, see 5.5. For the overall visitor pattern implementation, see 5.4.

---

Overview

The QueryString generator translates parsed Galach syntax trees into Elasticsearch Query String Query syntax. It is implemented in the QueryString class and shares substantial code with the ExtendedDisMax generator through Lucene common visitors. The primary difference between the two generators lies in character escaping rules: QueryString requires additional escaping for comparison operators (=, >, <).

Generator Structure

The QueryString generator follows the same architectural pattern as ExtendedDisMax:

Sources: lib/Languages/Galach/Generators/QueryString.php1-37 tests/Galach/Generators/QueryStringTest.php1-72

---

Generator Class

The QueryString class serves as the entry point for generation. It accepts a Visitor implementation (typically an Aggregate visitor) and delegates the traversal to that visitor.

Class Structure

Element	Type	Description
$visitor	Visitor	Aggregate visitor containing all node-specific visitors
__construct()	Constructor	Accepts a Visitor implementation
generate()	Method	Traverses syntax tree and returns Elasticsearch query string

Generation Process

The generate() method accepts a SyntaxTree and optional options parameter, then invokes the visitor on the root node:

This delegates all node-specific processing to the composed visitor collection.

Sources: lib/Languages/Galach/Generators/QueryString.php8-37

---

Visitor Configuration

The QueryString generator uses the same visitor composition as ExtendedDisMax, with one critical difference: it uses Lucene\QueryString\Word instead of Lucene\ExtendedDisMax\Word.

Required Visitors

The following visitors must be configured to create a functional QueryString generator:

Visitor Class	Purpose	Location
Lucene\Common\Prohibited	Handles -term syntax	Shared with ExtendedDisMax
Lucene\Common\Group	Handles parentheses grouping and domain prefixes	Shared with ExtendedDisMax
Lucene\Common\Mandatory	Handles +term syntax	Shared with ExtendedDisMax
Lucene\Common\LogicalAnd	Handles AND operators	Shared with ExtendedDisMax
Lucene\Common\LogicalNot	Handles NOT operators	Shared with ExtendedDisMax
Lucene\Common\LogicalOr	Handles OR operators	Shared with ExtendedDisMax
Lucene\Common\Phrase	Handles quoted phrases with field mapping	Shared with ExtendedDisMax
Lucene\Common\Query	Handles root query node	Shared with ExtendedDisMax
Lucene\Common\Tag	Translates #tag to field:value	Shared with ExtendedDisMax
Lucene\Common\User	Translates @user to field:value	Shared with ExtendedDisMax
Lucene\QueryString\Word	Handles word terms with QueryString escaping	QueryString-specific

Instantiation Example

Sources: tests/Galach/Generators/QueryStringTest.php38-71

---

Character Escaping

The primary difference between QueryString and ExtendedDisMax generators lies in character escaping. QueryString requires escaping for additional characters that represent comparison operators in Elasticsearch.

Escaping Comparison

QueryString Word Escaping

The Lucene\QueryString\Word visitor escapes the following characters:

Character	Reason	Example Input	Example Output
+	Mandatory operator	\+	\+
-	Prohibited operator	\-	\-
=	Comparison operator	\=	\\\=
>	Comparison operator	\>	\\\>
<	Comparison operator	\<	\\\<
&&	AND operator	\&&	\\\&&
`	`	OR operator
!	NOT operator	\!	\!
(, )	Grouping	\(	\(
{, }	Range queries	\{	\\\{
[, ]	Range queries	\[	\\\[
^	Boost operator	\^	\\\^
"	Phrase delimiter	\"	\"
~	Fuzzy/proximity	\~	\\\~
*	Wildcard	\*	\\\*
?	Wildcard	\?	\\\?
:	Field delimiter	\:	\:
/	Regex delimiter	\/	\\\/
\	Escape character	\\	\\
	Whitespace	\	\

The implementation uses a regular expression to identify and escape these characters:

Note the inclusion of \\=, \\>, and \\< in the pattern, which are not present in the ExtendedDisMax escaping pattern.

Sources: lib/Languages/Galach/Generators/Lucene/QueryString/Word.php1-27 lib/Languages/Galach/Generators/Lucene/ExtendedDisMax/Word.php1-27 tests/Galach/Generators/QueryStringTest.php13-32

---

Field Mapping

QueryString uses the same field mapping mechanism as ExtendedDisMax. Field mapping translates Galach domain prefixes to Elasticsearch field names.

Field Mapping Configuration

Visitors that support field mapping (Group, Phrase, and Word) accept two constructor parameters:

Parameter	Type	Description
$fieldMap	array	Maps domain names to Elasticsearch field names
$defaultField	string	Field name used for unrecognized or missing domains

Field Mapping Example

Translation Examples

Galach Input	Configuration	Elasticsearch Output
domain:one	domain → special_text_t	special_text_t:one
unexpected:one	No mapping, default: default_text_t	default_text_t:one
domain:"phrase"	domain → special_text_t	special_text_t:"phrase"
domain:(group)	domain → special_text_t	special_text_t:(group)
#tag	Tag field: tags_ms	tags_ms:tag
@user	User field: user_s	user_s:user

Sources: tests/Galach/Generators/ExtendedDisMaxTest.php16-20 tests/Galach/Generators/ExtendedDisMaxTest.php46-116

---

Translation Examples

The following table demonstrates complete query translations from Galach to Elasticsearch Query String format:

Basic Terms and Operators

Galach Input	Elasticsearch Output	Description
one	one	Simple word
'one'	'one'	Single-quoted word
"one"	"one"	Phrase
one two	one two	Multiple words
(one two)	(one two)	Grouped terms
one AND two	one AND two	Logical AND
one && two	one AND two	Alternative AND syntax
one OR two	one OR two	Logical OR
one || two	one OR two	Alternative OR syntax
NOT one	NOT one	Logical NOT
!one	NOT one	Alternative NOT syntax
+one	+one	Mandatory term
-one	-one	Prohibited term

Special Syntax

Galach Input	Elasticsearch Output	Description
@user	user_s:user	User mention (with user_s configured)
#tag	tags_ms:tag	Tag reference (with tags_ms configured)
domain:one	special_text_t:one	Domain-scoped term (with mapping)
unexpected:one	default_text_t:one	Unmapped domain uses default field

Escape Sequences

Galach Input	Elasticsearch Output	Description
\\	\\	Escaped backslash
\\+	\\+	Escaped mandatory operator
\\-	\\-	Escaped prohibited operator
\\=	\\\\\\\=	Escaped equals (QueryString-specific)
\\>	\\\\\\\>	Escaped greater-than (QueryString-specific)
\\<	\\\\\\\<	Escaped less-than (QueryString-specific)
\\*	\\\\\\\*	Escaped wildcard
\\?	\\\\\\\?	Escaped wildcard
\\!	\\!	Escaped NOT operator
\\	\\	Escaped space

Sources: tests/Galach/Generators/ExtendedDisMaxTest.php22-201 tests/Galach/Generators/QueryStringTest.php13-32

---

Usage Example

The following example demonstrates complete QueryString generator usage:

Step-by-Step Generation

Complete Code Flow

Sources: tests/Galach/Generators/QueryStringTest.php38-71 tests/Galach/Generators/ExtendedDisMaxTest.php210-222

---

Comparison with ExtendedDisMax

The QueryString and ExtendedDisMax generators share nearly identical implementations, differing only in the Word visitor escaping logic:

Similarities

• Same visitor collection (except Word visitor)
• Identical field mapping mechanism
• Same handling of logical operators, grouping, phrases
• Same translation of special syntax (#tag, @user)

Key Difference

Aspect	ExtendedDisMax	QueryString
Word Visitor	Lucene\ExtendedDisMax\Word	Lucene\QueryString\Word
Escape Pattern	`/(\+|-|&&|\	\
Extra Escaped Chars	None	=, >, <
Documentation Link	Lucene 5.0 QueryParser	Lucene 6.5 QueryParser

This design allows maximum code reuse while accommodating backend-specific escaping requirements.

Sources: lib/Languages/Galach/Generators/Lucene/ExtendedDisMax/Word.php19-26 lib/Languages/Galach/Generators/Lucene/QueryString/Word.php19-26