Query Processing#

This page provides an overview of query-processing workflows in the Squirro platform.


Query processing improves a user’s search experience by providing more relevant search results.

Squirro achieves this improvement by running each user query through a customizable query-processing workflow that parses, filters, enriches, and expands queries before performing the actual search and presenting the search results to the user.

Example: Part of speech (POS) boosting and filtering removes irrelevant terms like conjunctions from the query and gives more weight to relevant parts of the query, like nouns. The returned search results rank items that match boosted query terms higher.

Query-Processing Flow Diagram#

The figure below illustrates how query processing fits into Squirro’s overall architecture.

Overview of Squirro Query-Processing Workflow

In the example above, the user enters the query country:us 2020-10 covid cases in new york in the global search bar.

Squirro then sends the query through the Query Understanding Plugin (1) to the ML-Service where the query-processing workflow (a Squirro ML-Workflow) executes and applies the following steps on the incoming query:

  1. Language detection.

  2. Languag-specific spaCy analysis. This uses the pre-trained spaCy language model (see example) for the detected language. The analysis includes:

    • Tokenization and lemmatization

    • POS tagging

    • Named Entity Recognition (NER)

  3. POS booster and filer.

  4. Query modifier. The final query modifier step applies all modifications to the initial query to produce the Enriched Query (2) which is then used to retrieve the candidate documents that best match the query from the Elasticsearch index (3).

Query processing and rewriting improve the search experience by ranking items that match boosted terms higher and reducing the appearance of irrelevant search results for the query. It achieves this by combining terms that belong together. Entities like “New York “will be treated as such in the query, preventing multipage items (e.g., PDFs) that have “new” on one page and “york” on a different page from being matched and appearing in the search results.


Each project is pre-configured with a default query processing workflow. The workflow is installed on the server as a global asset and cannot be deleted via the user interface.

The query-processing workflow is enabled by default.

You can manage the behavior of the workflow in the project configuration under the Settings tab.






Disable query processing.



Enable query processing.



Set the value to the workflow_id of the ML-workflow you want to use for query processing. By default, the workflow_id is set to the ID of the pre-configured workflow that is setup upon project creation.



Execute workflow for every request to the /query endpoint. This mode is useful when Squirro is used as an API only.



Execute query processing workflow once for the whole dashboard (triggered via Global Search Bar widget).

Workflow Management#

Configuring Available Workflows#

You can configure the available workflows under AI Studio > ML Workflows.

Every project has a default query-processing workflow by default. This default workflow is read-only and cannot be deleted or modified. The Machine-Learning (ML) Service manages this and automatically updates it to the latest version.

The default query-processing workflow is set as the Active Query Processor and is listed along with any other custom workflow, as shown in the screen capture below:

Active Query in Hover State

If you want to customize the behavior of the default query-processing workflow, perform the following steps:

Caution: Following these steps will make the workflow you select the active query processor.

  1. Clone the workflow.

  2. Edit its configuration.

  3. Hover over the newly-created workflow and click Set Active.

The screen capture below shows how Set Active becomes visible on hover:

Setting the Active Query Workflow in the Squirro Dashboard

Disabling the Default Query-Processing Workflow#

The default query processing workflow cannot be deleted, but can be disabled. To disable query processing, perform the following:

  1. Navigate to Settings > Project Configuration.

  2. Change the topic.search.query-workflow-enabled option by clicking Edit.

  3. Uncheck the checkbox.

Query-Processing Workflow Steps#

For information on creating custom query-processing workflow steps, see How to Create Custom Query-Processing Steps.

The default query-processing workflow uses the following built-in libNLP app.query_processing steps:

Reference: Pre-configured Query Processing Pipeline Steps
  2    "cacheable": true,
  3    "dataset": {
  4        "items": []
  5    },
  6    "pipeline": [
  7        {
  8            "fields": ["query"],
  9            "step": "loader",
 10            "type": "squirro_item"
 11        },
 12        {
 13            "step": "app",
 14            "type": "query_processing",
 15            "name": "syntax_parser"
 16        },
 17        {
 18            "step": "app",
 19            "type": "query_processing",
 20            "name": "lang_detection",
 21            "fallback_language": "en"
 22        },
 23        {
 24            "step": "flow",
 25            "type": "condition",
 26            "condition": {
 27                "healthy_service": {
 28                    "service_name": "nlp"
 29                }
 30            },
 31            "true_step": {
 32                "step": "external",
 33                "type": "nlp_service_spacy",
 34                "name": "nlp_service_spacy",
 35                "field_mapping": {
 36                    "user_terms_str": "nlp"
 37                },
 38                "pipeline__default": "en:fast",
 39                "disable_pipes__default": ["merge_noun_chunks"],
 40                "language_processor_mapping": {
 41                    "de": "de:fast",
 42                    "en": "en:fast"
 43                }
 44            },
 45            "false_step": {
 46                "step": "app",
 47                "type": "query_processing",
 48                "name": "custom_spacy_normalizer",
 49                "model_cache_expiration": 345600,
 50                "infix_split_hyphen": false,
 51                "infix_split_chars": ":<>=",
 52                "merge_noun_chunks": false,
 53                "merge_phrases": true,
 54                "merge_entities": true,
 55                "fallback_language": "en",
 56                "exclude_spacy_pipes": [],
 57                "spacy_model_mapping": {
 58                    "en": "en_core_web_sm",
 59                    "de": "de_core_news_sm"
 60                }
 61            }
 62        },
 63        {
 64            "step": "app",
 65            "type": "query_processing",
 66            "name": "pos_booster",
 67            "phrase_proximity_distance": 10,
 68            "min_query_length": 2,
 69            "pos_weight_map": {
 70                "PROPN": "-",
 71                "NOUN": "-",
 72                "VERB": "-",
 73                "ADV": "-",
 74                "CCONJ": "-",
 75                "ADP": "-",
 76                "ADJ": "-",
 77                "X": "-",
 78                "NUM": "-",
 79                "SYM": "-"
 80            }
 81        },
 82        {
 83            "step": "app",
 84            "type": "query_processing",
 85            "name": "lemma_tagger"
 86        },
 87        {
 88            "step": "app",
 89            "type": "query_processing",
 90            "name": "query_classifier",
 91            "model": "svm-query-classifier"
 92        },
 93        {
 94            "step": "app",
 95            "type": "query_processing",
 96            "name": "query_modifier"
 97        },
 98        {
 99            "step": "debugger",
100            "type": "log_fields",
101            "fields": [
102                "user_terms",
103                "facet_filters",
104                "pos_mutations",
105                "type",
106                "enriched_query",
107                "lemma_map"
108            ],
109            "log_level": "info"
110        }
111    ]

The workflow is set to:

  • Parse Squirro query syntax and detect query Language based on available natural language terms.

  • Perform named entity recognition (NER). The entity compound is then rewritten into an additional phrase query.

    Example: cases in new york –> rewritten as –> cases in(new york OR "new york"~10)

  • Boost important terms based on their POS tags. (For more information, see Universal POS tags).

    Example: Boost nouns (tags NOUN and PROPN) by assigning higher weights in the pos_weight_map.

    Example: Reduce the impact of verbs (VERB) by assigning lower weights.

  • Remove terms like determiners and conjunctions from the query.

  • Perform query classification: question_or_statement vs keyword.

Reminder: You can configure the steps of the query-processing workflow in AI Studio.

Creating Custom Query-Processing Steps#

See How to Create Custom Query-Processing Steps for instructions on how to create custom query-processing steps.