### Custom Elasticsearch Query Builder

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Create a custom ElasticsearchQueryBuilder by inheriting from the base class and overriding element handlers, for example, to use 'match' instead of 'term' for words.

```python
from luqum.elasticsearch.visitor import EWord, ElasticsearchQueryBuilder
from luqum.tree import AndOperation

class EWordMatch(EWord):
    @property
    def json(self):
         if self.q == '*':
             return super().json
         return {"match": {self.field: self.q}}

class MyElasticsearchQueryBuilder(ElasticsearchQueryBuilder):
    E_WORD = EWordMatch

transformer = MyElasticsearchQueryBuilder()
q = 'message:* AND author:John AND link_type:action'
tree = parser.parse(q)
query = transformer(tree)
```

--------------------------------

### Generate HTML with Matched Query Parts

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Use HTMLMarker to render the query tree in HTML, visually indicating which parts matched (ok) and which did not (ko) based on the processed matching paths.

```python
>>> from luqum.naming import HTMLMarker
>>> mark_html = HTMLMarker()  # you can customize some parameters, refer to doc
>>> mark_html(tree, paths_ok, paths_ko)
'<span class="ok"><span class="ko">foo~2 </span>OR (<span class="ko"><span class="ok">bar </span>AND baz</span>)</span>'
```

--------------------------------

### Pretty Print Luqum Queries

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Use the prettify function from luqum.pretty to format complex parsed queries into a more readable, multi-line structure.

```default
>>> from luqum.pretty import prettify
>>> tree = parser.parse(
...     'some_long_field:("some long value" OR "another quite long expression"~2 OR "even something more expanded"^4) AND yet_another_fieldname:[a_strange_value TO z]')
>>> print(prettify(tree))
```

```default
some_long_field: (
    "some long value"
    OR
    "another quite long expression"~2
    OR
    "even something more expanded"^4
)
AND
yet_another_fieldname: [a_strange_value TO z]
```

--------------------------------

### Initialize TestCase

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Initializes a TestCase object for assertions. Set maxDiff to None to see full diffs.

```python
>>> from unittest import TestCase
>>> t = TestCase()
>>> t.maxDiff = None
```

--------------------------------

### Resolve Unknown Operations with Luqum

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Use UnknownOperationResolver to replace implicit OR/AND operators with explicit ones like ANDOperation or OrOperation.

```default
>>> tree = parser.parse('foo bar')
>>> tree
UnknownOperation(Word('foo'), Word('bar'))
```

```pycon
>>> from luqum.utils import UnknownOperationResolver
>>> resolver = UnknownOperationResolver()
>>> str(resolver(tree))
'foo AND bar'
```

--------------------------------

### Preserve Formatting with Head and Tail in Luqum

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Manually set head and tail attributes on Word elements to preserve meaningful spacing and characters in expressions. This is useful when building trees programmatically.

```default
>>> from luqum.tree import AndOperation, Word
>>> my_tree =  AndOperation(Word('foo'), Word('bar'))
```

```default
>>> print(my_tree)
fooANDbar
```

```pycon
>>> my_tree =  AndOperation(Word('foo', tail=" "), Word('bar', head=" "))
>>> print(my_tree)
foo AND bar
```

--------------------------------

### Auto-Add Head/Tail with Luqum Utility

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Utilize the auto_head_tail function to automatically add minimal head and tail spacing to elements in a Luqum tree, ensuring proper formatting.

```default
>>> from luqum.tree import Not
>>> from luqum.auto_head_tail import auto_head_tail
>>> my_tree =  AndOperation(Word('foo'), Not(Word('bar')))
>>> my_tree = auto_head_tail(my_tree)
>>> print(my_tree)
foo AND NOT bar
```

--------------------------------

### Verify Custom Generated Query

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Assert that the custom query builder generates the expected query DSL, using 'match' for specified fields.

```python
t.assertDictEqual(
    query,
    {'bool': {'must': [
        {'exists': {'field': 'message'}},
        {'match': {'author': 'John'}},
        {'match': {'link_type': 'action'}}]}})
)
```

--------------------------------

### Print AST Representation

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Prints the string representation of the parsed query AST. This is useful for debugging and understanding the structure.

```python
>>> print(repr(tree))
```

--------------------------------

### Parse Lucene Query

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Parses a Lucene query string into an abstract syntax tree (AST). Import the parser from luqum.parser.

```python
>>> from luqum.parser import parser
>>> tree = parser.parse('(title:"foo bar" AND body:"quick fox") OR title:fox')
```

--------------------------------

### Generate Elasticsearch Query Builder

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Instantiate SchemaAnalyzer with your Elasticsearch schema and use its options to create an ElasticsearchQueryBuilder.

```python
schema_analizer = SchemaAnalyzer(MESSAGES_SCHEMA)
message_es_builder = ElasticsearchQueryBuilder(**schema_analizer.query_builder_options())
```

--------------------------------

### Parse and Build Elasticsearch Query

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Parse a query string and use the ElasticsearchQueryBuilder to generate the corresponding Elasticsearch query DSL.

```python
q = 'message:"exciting news" AND author.given_name:John AND references.link_type:action'
tree = parser.parse(q)
query = message_es_builder(tree)
```

--------------------------------

### Build Elasticsearch Query with Named Parts

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Generate an Elasticsearch query from the Luqum tree. The generated query includes '_name' fields for matched parts, corresponding to the names assigned by auto_name.

```python
>>> es_query = es_builder(tree)
>>> t.assertDictEqual(
...     es_query,
...     {'bool': {'should': [
...         {'fuzzy': {'text': {'fuzziness': 2.0, 'value': 'foo', '_name': 'a'}}}, 
...         {'bool': {'must': [
...             {'match': {'text': {'query': 'bar', 'zero_terms_query': 'all', '_name': 'c'}}}, 
...             {'match': {'text': {'query': 'baz', 'zero_terms_query': 'all', '_name': 'd'}}}
...         ]}}
...     ]}}
... )
```

--------------------------------

### Identify Matching Query Parts

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Process the matched query names returned by Elasticsearch to identify which parts of the original query tree were matched. This uses MatchingPropagator and matching_from_names.

```python
>>> matched_queries = ['b', 'c']
>>> from luqum.naming import MatchingPropagator, matching_from_names
>>> propagate_matching = MatchingPropagator()
>>> paths_ok, paths_ko = propagate_matching(tree, *matching_from_names(matched_queries, names))
```

--------------------------------

### Parse a Query String

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Use the parser to convert a query string into a structured tree.

```python
>>> expr = "foo~2 OR (bar AND baz)"
>>> tree = parser.parse(expr)
```

--------------------------------

### Retrieve Query Elements by Name or Path

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Access specific elements in the query tree using their assigned names or their structural path. Requires the parsed tree and the names dictionary generated by auto_name.

```python
>>> from luqum.naming import element_from_path, element_from_name
>>> element_from_name(tree, "a", names)
Fuzzy(Word('foo'), 2)
>>> element_from_path(tree, (0, 0))
Word('foo')
```

--------------------------------

### Transform Lucene to Elasticsearch DSL (Basic)

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Transforms a parsed Lucene query AST into an Elasticsearch Query DSL dictionary. Specify not_analyzed_fields to treat them as terms.

```python
>>> from luqum.elasticsearch import ElasticsearchQueryBuilder
>>> es_builder = ElasticsearchQueryBuilder(not_analyzed_fields=["published", "tag"])

>>> tree = parser.parse('''
...     title:("brown fox" AND quick AND NOT dog) AND
...     published:[* TO 1990-01-01T00:00:00.000Z] AND
...     tag:fable
...     ''')
>>> query = es_builder(tree)
>>> t.assertDictEqual(
...     query,
...     {'bool': {'must': [
...         {'bool': {'must': [
...             {'match_phrase': {'title': {'query': 'brown fox'}}},
...             {'match': {'title': {'query': 'quick', 'zero_terms_query': 'all'}}},
...             {'bool': {'must_not': [
...                 {'match': {'title': {'query': 'dog', 'zero_terms_query': 'none'}}}]}}]}},
...         {'range': {'published': {'lte': '1990-01-01T00:00:00.000Z'}}},
...         {'term': {'tag': {'value': 'fable'}}}]}})
```

--------------------------------

### Transform Query AST with TreeTransformer

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Uses a custom TreeTransformer to recursively visit and potentially modify nodes in the query AST. This is the recommended way to manipulate queries.

```python
>>> from luqum.visitor import TreeTransformer
>>> class MyTransformer(TreeTransformer):
...     def visit_search_field(self, node, context):
...         if node.expr.value == '"lazy dog"':
...             new_node = node.clone_item()
...             new_node.expr = node.expr.clone_item(value = '"back to foo bar"')
...             yield new_node
...         else:
...             yield from self.generic_visit(node, context)
...
>>> transformer = MyTransformer()
>>> new_tree = transformer.visit(tree)
>>> print(str(new_tree))
```

--------------------------------

### Verify Generated Elasticsearch Query

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Assert that the generated Elasticsearch query matches the expected structure.

```python
t.assertDictEqual(
    query,
    {'bool': {'must': [
        {'match_phrase': {'message':
            {'query': 'exciting news'}}}
        {'term': {'author.given_name': {'value': 'John'}}}
        {'nested':
            {'path': 'references',
             'query': {'term': {'references.link_type': {'value': 'action'}}},
            },
        },
    ]}})
)
```

--------------------------------

### Transform Lucene to Elasticsearch DSL (Nested and Object Fields)

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Transforms a parsed Lucene query AST to Elasticsearch DSL, supporting nested and object fields. Configure nested_fields and object_fields in the builder.

```python
>>> es_builder = ElasticsearchQueryBuilder(
...     nested_fields={"authors": {"given_name", "last_name", "city"}},
...     object_fields=["authors.city.name"])
>>> tree = parser.parse('''
...     title:"quick brown fox" AND
...     authors:(given_name:Ja* AND last_name:London AND city.name:"San Francisco")
...     ''')
>>> query = es_builder(tree)
>>> t.assertDictEqual(
...     query,
...     {'bool': {'must': [
...         {'match_phrase': {'title':
...              {'query': 'quick brown fox'}}},
...         {'nested': {
...             'query': {'bool': {'must': [
...                 {'query_string': {
...                     'default_field': 'authors.given_name',
...                     'analyze_wildcard': True,
...                     'query': 'Ja*',
...                     'allow_leading_wildcard': True}},
...                 {'match': {
...                     'authors.last_name': {
...                     'query': 'London',
...                     'zero_terms_query': 'all'}}},
...                 {'match_phrase': {'authors.city.name': {
...                     'query': 'San Francisco'}}}]}},
...             'path': 'authors'}}]}})
```

--------------------------------

### Convert AST to String

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Converts the query AST back into a standard Lucene query string using Python's str() method.

```python
>>> print(str(tree))
```

--------------------------------

### Automatically Name Query Elements

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Utilize auto_name to assign names to elements within the parsed query tree. This is useful for referencing specific parts of the query later.

```python
>>> from luqum.naming import auto_name
>>> names = auto_name(tree)
```

--------------------------------

### Modify Query AST Value

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Directly modifies a value within the query AST. Note that this is a manual approach and may be tedious for complex trees.

```python
>>> tree.children[0].children[0].children[0].children[0].value = '"lazy dog"'
>>> print(str(tree))
```

--------------------------------

### Define Elasticsearch Schema

Source: https://github.com/jurismarches/luqum/blob/master/docs/source/quick_start.md

Define the schema for your Elasticsearch index. This schema is used by SchemaAnalyzer to deduce query builder options.

```python
MESSAGES_SCHEMA = {
    "settings": {"query": {"default_field": "message"}},
    "mappings": {
        "type1": {
            "properties": {
                "message": { "type": "text" },
                "created": { "type": "date" },
                "author": {
                    "type": "object",
                    "properties": {
                        "given_name": { "type": "keyword" },
                        "last_name": { "type": "keyword" },
                    },
                },
                "references": {
                    "type": "nested",
                    "properties": {
                        "link_type": { "type": "keyword" },
                        "link_url": {"type": "keyword"},
                    },
                },
            },
        },
    },
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.