Query Parser Engine

Relevant source files

The following files were used as context for generating this wiki page:

• src/query/SearchParser.cpp
• src/query/SearchParser.h
• src/query/SqlQueryBuilder.cpp
• src/query/SqlQueryBuilder.h
• src/domain/SsaTypes.h
• src/infra/sqlite/SqliteConnection.cpp
• tests/unit/SearchParserTests.cpp

The Query Parser Engine is a core component of the SSA Consulta Rapida Cpp project responsible for transforming raw user input strings into structured search expressions and ultimately into executable SQL queries. It resides in the src/query layer, maintaining strict separation from the UI and raw infrastructure logic. Sources: AGENTS.md:21, src/query/SearchParser.h

This engine handles tokenization of search terms, identification of specialized search modes (such as prefix or regex matching), and the compilation of these terms into parameterized SQLite statements. Sources: src/query/SearchParser.cpp, src/query/SqlQueryBuilder.cpp

Architecture and Data Flow

The engine operates as a pipeline where a raw string is first parsed into domain-specific objects and then handed to a builder to generate SQL.

Components

1. SearchParser: Responsible for splitting input by commas (implicit AND logic) and identifying modifiers for negation or specific match modes. Sources: src/query/SearchParser.cpp:51-68, tests/unit/SearchParserTests.cpp:5-10
2. SqlQueryBuilder: Consumes the parsed expression along with pagination and sorting metadata to construct complete SELECT and COUNT statements. Sources: src/query/SqlQueryBuilder.cpp:151-177
3. SearchExpression: A data structure holding a collection of FilterTerm objects derived from the input. Sources: src/query/SearchParser.h:13-15

Search Syntax and Tokenization

The SearchParser identifies specific characters at the start or end of a search chunk to determine the MatchMode.

Supported Match Modes

Prefix/Suffix	Match Mode	Description
! or -	Negation	Excludes the term from results (NOT)
^	StartsWith	Matches records beginning with the term
$	EndsWith	Matches records ending with the term
=	Equals	Exact case-insensitive match
~	Regex	Regular expression matching
(None)	Contains	Default substring match (%text%)

Sources: src/query/SearchParser.cpp:24-46, src/domain/SsaTypes.h:79-85, tests/unit/SearchParserTests.cpp:12-21

Parsing Logic

The parser treats commas as delimiters. Each "chunk" is trimmed of whitespace before the engine evaluates leading symbols for negation and mode selection. Sources: src/query/SearchParser.cpp:9-22, tests/unit/SearchParserTests.cpp:7-9

SQL Compilation

The SqlQueryBuilder converts domain objects into parameterized SQL. This ensures protection against SQL injection by using ? placeholders and a bindings vector. Sources: src/query/SqlQueryBuilder.cpp:168-174, tests/unit/SqlQueryBuilderTests.cpp:5-15

Query Generation Process

• Column Selection: Uses the ColumnCatalog to determine which columns to include in the SELECT clause. Sources: src/query/SqlQueryBuilder.cpp:26-31
• Where Clause Construction: Combines general search terms, column-specific filters, and hardcoded exclusions (like SCA, SES, STE status exclusions). Sources: src/query/SqlQueryBuilder.cpp:108-132
• Pattern Mapping: Converts FilterTerm modes into SQL syntax (e.g., LIKE ? or REGEXP ?). Sources: src/query/SqlQueryBuilder.cpp:54-61

Regex Support

Since SQLite does not provide a native REGEXP implementation by default, the project registers a custom C++ function to the SQLite connection using std::regex. Sources: src/infra/sqlite/SqliteConnection.cpp:11-37, tests/unit/SqlQueryBuilderTests.cpp:24-30

// Example of how match modes translate to SQL patterns
if (term.mode == domain::MatchMode::StartsWith) {
    return text + "%"; // Used with LIKE
}
if (term.mode == domain::MatchMode::Regex) {
    return text; // Used with REGEXP
}

Sources: src/query/SqlQueryBuilder.cpp:35-48

Conclusion

The Query Parser Engine provides a robust and flexible search interface for the SSA system. By decoupling the syntax parsing from SQL generation, the system supports complex queries (including regex and negation) while maintaining performance through database-level filtering and protection through parameter binding. Sources: src/query/SqlQueryBuilder.cpp, src/query/SearchParser.cpp