tessl/pypi-elasticsearch-dsl
High-level Python library for Elasticsearch providing an idiomatic way to write and manipulate queries.
—
Pending
search-queries.mddocs/
Search and Queries
Fluent API for building and executing Elasticsearch queries with comprehensive support for filtering, full-text search, sorting, pagination, and result processing. The query system mirrors Elasticsearch's JSON DSL while providing a Pythonic interface for both simple and complex search operations.
Capabilities
Search Class
Main search request builder with fluent API for constructing and executing queries.
class Search:
"""
Search request builder with fluent API.
"""
def __init__(self, using=None, index=None, doc_type=None):
"""
Initialize search request.
Args:
using (str, optional): Connection alias to use
index (str or list, optional): Index name(s) to search
doc_type (str, optional): Document type (deprecated in ES 7+)
"""
def query(self, query, **kwargs):
"""
Add query to search request.
Args:
query (str or Query): Query name or Query object
**kwargs: Query parameters if query is a string
Returns:
Search: New Search instance with query applied
"""
def filter(self, query, **kwargs):
"""
Add filter to search request (executed in filter context).
Args:
query (str or Query): Filter name or Query object
**kwargs: Filter parameters if query is a string
Returns:
Search: New Search instance with filter applied
"""
def exclude(self, query, **kwargs):
"""
Add exclusion filter to search request.
Args:
query (str or Query): Filter name or Query object
**kwargs: Filter parameters if query is a string
Returns:
Search: New Search instance with exclusion applied
"""
def sort(self, *keys):
"""
Add sorting to search request.
Args:
*keys: Sort keys (str, dict, or SortField objects)
Returns:
Search: New Search instance with sorting applied
"""
def extra(self, **kwargs):
"""
Add extra parameters to search request.
Args:
**kwargs: Additional search parameters
Returns:
Search: New Search instance with extra parameters
"""
def params(self, **kwargs):
"""
Add URL parameters to search request.
Args:
**kwargs: URL parameters
Returns:
Search: New Search instance with parameters
"""
def source(self, fields=None, **kwargs):
"""
Configure source field filtering.
Args:
fields (list or bool, optional): Fields to include/exclude
**kwargs: Source filtering parameters
Returns:
Search: New Search instance with source filtering
"""
def highlight(self, *fields, **kwargs):
"""
Add highlighting to search request.
Args:
*fields: Fields to highlight
**kwargs: Highlighting parameters
Returns:
Search: New Search instance with highlighting
"""
def suggest(self, name, text, **kwargs):
"""
Add suggestion to search request.
Args:
name (str): Suggestion name
text (str): Text to get suggestions for
**kwargs: Suggestion parameters
Returns:
Search: New Search instance with suggestion
"""
def from_(self, from_):
"""
Set starting offset for pagination.
Args:
from_ (int): Starting offset
Returns:
Search: New Search instance with offset
"""
def size(self, size):
"""
Set number of results to return.
Args:
size (int): Number of results
Returns:
Search: New Search instance with size limit
"""
def execute(self, ignore_cache=False):
"""
Execute search request.
Args:
ignore_cache (bool): Ignore cached results
Returns:
Response: Search response with results
"""
def scan(self):
"""
Execute search using scan and scroll for large result sets.
Returns:
generator: Generator yielding Hit objects
"""
def count(self):
"""
Get total count of matching documents.
Returns:
int: Count of matching documents
"""
def delete(self):
"""
Delete documents matching the search query.
Returns:
dict: Delete by query response
"""
def to_dict(self):
"""
Convert search to dictionary representation.
Returns:
dict: Search request as dictionary
"""
@classmethod
def from_dict(cls, d):
"""
Create Search from dictionary.
Args:
d (dict): Search request dictionary
Returns:
Search: Search instance
"""Async Search
Asynchronous version of Search class for async/await operations.
class AsyncSearch:
"""
Async version of Search class.
"""
async def execute(self, ignore_cache=False):
"""
Async execute search request.
Args:
ignore_cache (bool): Ignore cached results
Returns:
Response: Search response with results
"""
async def count(self):
"""
Async get total count of matching documents.
Returns:
int: Count of matching documents
"""
async def delete(self):
"""
Async delete documents matching the search query.
Returns:
dict: Delete by query response
"""Multi-Search Operations
Execute multiple search requests in a single request for improved performance.
class MultiSearch:
"""
Execute multiple search requests in a single request.
"""
def __init__(self, using=None, index=None):
"""
Initialize multi-search request.
Args:
using (str, optional): Connection alias to use
index (str or list, optional): Default index name(s)
"""
def add(self, search):
"""
Add search request to multi-search.
Args:
search (Search): Search request to add
Returns:
MultiSearch: Current MultiSearch instance
"""
def execute(self, ignore_cache=False, raise_on_error=True):
"""
Execute all search requests.
Args:
ignore_cache (bool): Ignore cached results
raise_on_error (bool): Raise exception on any search error
Returns:
list: List of Response objects for each search
"""
def to_dict(self):
"""
Convert multi-search to dictionary representation.
Returns:
dict: Multi-search request as dictionary
"""
class AsyncMultiSearch:
"""
Async version of MultiSearch for async/await operations.
"""
def __init__(self, using=None, index=None):
"""
Initialize async multi-search request.
Args:
using (str, optional): Connection alias to use
index (str or list, optional): Default index name(s)
"""
def add(self, search):
"""
Add async search request to multi-search.
Args:
search (AsyncSearch): Async search request to add
Returns:
AsyncMultiSearch: Current AsyncMultiSearch instance
"""
async def execute(self, ignore_cache=False, raise_on_error=True):
"""
Async execute all search requests.
Args:
ignore_cache (bool): Ignore cached results
raise_on_error (bool): Raise exception on any search error
Returns:
list: List of Response objects for each search
"""Query Factory Function
Main query factory function for creating query objects.
def Q(name=None, **params):
"""
Create query object.
Args:
name (str, optional): Query type name
**params: Query parameters
Returns:
Query: Query object
Examples:
Q('match', title='python')
Q('bool', must=[Q('term', status='published')])
Q({'match': {'title': 'python'}}) # From dict
"""Common Query Types
Full-Text Queries
class Match:
"""
Match query for full-text search.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-value pairs and query parameters
Parameters:
query (str): Query text
operator (str): 'and' or 'or' (default: 'or')
minimum_should_match (str or int): Minimum should match
analyzer (str): Analyzer to use
fuzziness (str or int): Fuzziness for fuzzy matching
prefix_length (int): Prefix length for fuzzy matching
max_expansions (int): Max expansions for fuzzy matching
boost (float): Query boost
"""
class MultiMatch:
"""
Multi-field match query.
"""
def __init__(self, query, fields=None, **kwargs):
"""
Args:
query (str): Query text
fields (list): Fields to search
**kwargs: Additional parameters
Parameters:
type (str): Multi-match type ('best_fields', 'most_fields', etc.)
operator (str): 'and' or 'or'
minimum_should_match (str or int): Minimum should match
analyzer (str): Analyzer to use
boost (float): Query boost
tie_breaker (float): Tie breaker for scoring
"""
class MatchPhrase:
"""
Match phrase query for exact phrase matching.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-value pairs and query parameters
Parameters:
slop (int): Allowed distance between terms
analyzer (str): Analyzer to use
boost (float): Query boost
"""
class MatchPhrasePrefix:
"""
Match phrase prefix query for phrase with prefix matching.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-value pairs and query parameters
Parameters:
slop (int): Allowed distance between terms
max_expansions (int): Max expansions for prefix
analyzer (str): Analyzer to use
boost (float): Query boost
"""Term-Level Queries
class Term:
"""
Exact term match query.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-value pairs and query parameters
Parameters:
boost (float): Query boost
case_insensitive (bool): Case insensitive matching
"""
class Terms:
"""
Multiple exact terms match query.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-list pairs and query parameters
Parameters:
boost (float): Query boost
"""
class Range:
"""
Range query for numeric and date ranges.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-range pairs and query parameters
Parameters:
gte: Greater than or equal to
gt: Greater than
lte: Less than or equal to
lt: Less than
format (str): Date format for date fields
time_zone (str): Time zone for date fields
boost (float): Query boost
"""
class Exists:
"""
Check field existence query.
"""
def __init__(self, field):
"""
Args:
field (str): Field to check for existence
"""
class Prefix:
"""
Prefix match query.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-prefix pairs and query parameters
Parameters:
boost (float): Query boost
case_insensitive (bool): Case insensitive matching
"""
class Wildcard:
"""
Wildcard pattern query.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-pattern pairs and query parameters
Parameters:
boost (float): Query boost
case_insensitive (bool): Case insensitive matching
"""
class Regexp:
"""
Regular expression query.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-pattern pairs and query parameters
Parameters:
flags (str): Regular expression flags
max_determinized_states (int): Max determinized states
boost (float): Query boost
"""
class Fuzzy:
"""
Fuzzy string matching query.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Field-value pairs and query parameters
Parameters:
fuzziness (str or int): Fuzziness level
prefix_length (int): Prefix length
max_expansions (int): Max expansions
transpositions (bool): Allow transpositions
boost (float): Query boost
"""Compound Queries
class Bool:
"""
Boolean query combining must/should/must_not/filter clauses.
"""
def __init__(self, must=None, should=None, must_not=None, filter=None, **kwargs):
"""
Args:
must (list, optional): Queries that must match
should (list, optional): Queries that should match
must_not (list, optional): Queries that must not match
filter (list, optional): Queries that must match (filter context)
**kwargs: Additional parameters
Parameters:
minimum_should_match (str or int): Minimum should match
boost (float): Query boost
"""
class DisMax:
"""
Disjunction max query.
"""
def __init__(self, queries=None, tie_breaker=None, **kwargs):
"""
Args:
queries (list): List of queries
tie_breaker (float): Tie breaker for scoring
**kwargs: Additional parameters
"""
class FunctionScore:
"""
Function score query for custom scoring.
"""
def __init__(self, query=None, functions=None, **kwargs):
"""
Args:
query (Query, optional): Base query
functions (list, optional): Scoring functions
**kwargs: Additional parameters
Parameters:
score_mode (str): How to combine function scores
boost_mode (str): How to combine with query score
max_boost (float): Maximum boost value
min_score (float): Minimum score threshold
"""
class Boosting:
"""
Boosting query for positive and negative boosting.
"""
def __init__(self, positive=None, negative=None, negative_boost=None, **kwargs):
"""
Args:
positive (Query): Positive query
negative (Query): Negative query
negative_boost (float): Negative boost factor
**kwargs: Additional parameters
"""
class ConstantScore:
"""
Constant score query that wraps a filter and returns constant score.
"""
def __init__(self, filter=None, boost=1.0, **kwargs):
"""
Args:
filter (Query): Filter query to wrap
boost (float): Constant score to return
**kwargs: Additional parameters
"""
class Nested:
"""
Nested query for nested objects.
"""
def __init__(self, path=None, query=None, **kwargs):
"""
Args:
path (str): Path to nested object
query (Query): Query to run on nested documents
**kwargs: Additional parameters
Parameters:
score_mode (str): How to score nested hits ('avg', 'max', 'min', 'sum', 'none')
ignore_unmapped (bool): Ignore unmapped fields
inner_hits (dict): Inner hits configuration
"""
class HasChild:
"""
Parent-child has child query.
"""
def __init__(self, type=None, query=None, **kwargs):
"""
Args:
type (str): Child document type
query (Query): Query to run on child documents
**kwargs: Additional parameters
Parameters:
score_mode (str): How to score parent docs ('min', 'max', 'sum', 'avg', 'none')
min_children (int): Minimum number of matching children
max_children (int): Maximum number of matching children
ignore_unmapped (bool): Ignore unmapped types
inner_hits (dict): Inner hits configuration
"""
class HasParent:
"""
Parent-child has parent query.
"""
def __init__(self, parent_type=None, query=None, **kwargs):
"""
Args:
parent_type (str): Parent document type
query (Query): Query to run on parent documents
**kwargs: Additional parameters
Parameters:
score (bool): Include parent score in child documents
ignore_unmapped (bool): Ignore unmapped types
inner_hits (dict): Inner hits configuration
"""
class ParentId:
"""
Parent-child parent ID query.
"""
def __init__(self, type=None, id=None, **kwargs):
"""
Args:
type (str): Child document type
id (str): Parent document ID
**kwargs: Additional parameters
Parameters:
ignore_unmapped (bool): Ignore unmapped types
"""Search Response Handling
class Response:
"""
Search response wrapper.
"""
hits: list # List of Hit objects
aggregations: dict # Aggregation results
suggest: dict # Suggestion results
def __len__(self):
"""Return number of hits."""
def __iter__(self):
"""Iterate over hits."""
def __getitem__(self, key):
"""Get hit by index."""
class Hit:
"""
Individual search result wrapper.
"""
meta: Meta # Hit metadata (score, id, index, etc.)
def to_dict(self):
"""Convert hit to dictionary."""Usage Examples
Basic Search Operations
from elasticsearch_dsl import Search, Q, connections
# Configure connection
connections.create_connection(hosts=['localhost:9200'])
# Simple search
search = Search(index='blog')
search = search.query('match', title='python')
response = search.execute()
for hit in response:
print(f"Title: {hit.title}, Score: {hit.meta.score}")
# Complex boolean query
search = Search(index='blog')
search = search.query(
Q('bool',
must=[
Q('match', title='python'),
Q('range', published_date={'gte': '2023-01-01'})
],
should=[
Q('match', tags='tutorial'),
Q('match', tags='beginner')
],
minimum_should_match=1
)
)
response = search.execute()
print(f"Found {response.hits.total.value} articles")Filtering and Sorting
# Add filters and sorting
search = Search(index='blog')
search = search.filter('term', status='published')
search = search.filter('range', published_date={'gte': '2023-01-01'})
search = search.exclude('term', tags='draft')
search = search.sort('-published_date', '_score')
# Pagination
search = search.from_(0).size(10)
response = search.execute()Advanced Query Patterns
# Multi-field search with boosting
search = Search(index='blog')
search = search.query(
Q('multi_match',
query='python elasticsearch',
fields=['title^2', 'content', 'tags^1.5'],
type='best_fields',
tie_breaker=0.3
)
)
# Function score for custom relevance
search = Search(index='blog')
search = search.query(
Q('function_score',
query=Q('match', content='python'),
functions=[
{
'filter': Q('range', published_date={'gte': '2023-01-01'}),
'weight': 2
},
{
'field_value_factor': {
'field': 'view_count',
'factor': 0.1,
'modifier': 'log1p'
}
}
],
score_mode='sum',
boost_mode='multiply'
)
)
response = search.execute()Highlighting and Source Filtering
# Add highlighting and source filtering
search = Search(index='blog')
search = search.query('match', content='python')
search = search.highlight(
'title', 'content',
fragment_size=150,
number_of_fragments=3,
pre_tags=['<mark>'],
post_tags=['</mark>']
)
search = search.source(['title', 'published_date', 'author'])
response = search.execute()
for hit in response:
print(f"Title: {hit.title}")
if hasattr(hit.meta, 'highlight'):
for fragment in hit.meta.highlight.content:
print(f" Excerpt: {fragment}")Install with Tessl CLI
npx tessl i tessl/pypi-elasticsearch-dsl