tessl/pypi-elasticsearch-dsl
High-level Python library for Elasticsearch providing an idiomatic way to write and manipulate queries.
—
Pending
field-types.mddocs/
Field Types
Comprehensive field type system for defining document structure and Elasticsearch mappings. Each field type corresponds to an Elasticsearch mapping type and provides validation, serialization, and deserialization capabilities with support for all Elasticsearch field parameters and options.
Capabilities
Text Fields
Full-text search fields with analyzer support for natural language processing and search.
class Text:
"""
Full-text field for analyzed text content.
"""
def __init__(self, analyzer=None, search_analyzer=None, fields=None, **kwargs):
"""
Args:
analyzer (str, optional): Analyzer for indexing
search_analyzer (str, optional): Analyzer for searching
fields (dict, optional): Multi-fields mapping
**kwargs: Additional text field parameters
Parameters:
boost (float): Field boost for relevance scoring
eager_global_ordinals (bool): Load global ordinals eagerly
fielddata (bool): Enable fielddata for aggregations/sorting
fielddata_frequency_filter (dict): Fielddata frequency filtering
index (bool): Index this field for search (default: True)
index_options (str): Index options ('docs', 'freqs', 'positions', 'offsets')
index_prefixes (dict): Index prefixes configuration
index_phrases (bool): Index two-term word combinations
norms (bool): Store length normalization factors
position_increment_gap (int): Gap between array elements
store (bool): Store field value separately
search_quote_analyzer (str): Analyzer for quoted searches
similarity (str): Similarity algorithm to use
term_vector (str): Term vector storage options
"""
class Keyword:
"""
Exact-value field for filtering, sorting, and aggregations.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Keyword field parameters
Parameters:
boost (float): Field boost for relevance scoring
doc_values (bool): Store doc values for aggregations/sorting
eager_global_ordinals (bool): Load global ordinals eagerly
fields (dict): Multi-fields mapping
ignore_above (int): Ignore strings longer than this value
index (bool): Index this field for search (default: True)
index_options (str): Index options
norms (bool): Store length normalization factors
null_value (str): Value to use for null values
store (bool): Store field value separately
similarity (str): Similarity algorithm to use
normalizer (str): Normalizer to apply
split_queries_on_whitespace (bool): Split queries on whitespace
"""Numeric Fields
Numeric field types for mathematical operations, range queries, and aggregations.
class Integer:
"""
32-bit signed integer field.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Integer field parameters
Parameters:
boost (float): Field boost for relevance scoring
doc_values (bool): Store doc values for aggregations/sorting
ignore_malformed (bool): Ignore malformed values
index (bool): Index this field for search (default: True)
meta (dict): Metadata about the field
null_value (int): Value to use for null values
store (bool): Store field value separately
"""
class Long:
"""
64-bit signed integer field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""
class Float:
"""
32-bit floating point field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""
class Double:
"""
64-bit floating point field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""
class Short:
"""
16-bit signed integer field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""
class Byte:
"""
8-bit signed integer field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""
class HalfFloat:
"""
16-bit floating point field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""
class ScaledFloat:
"""
Floating point backed by long with scaling factor.
"""
def __init__(self, scaling_factor, **kwargs):
"""
Args:
scaling_factor (int): Scaling factor for the value
**kwargs: Additional parameters same as Integer
"""
class UnsignedLong:
"""
64-bit unsigned integer field.
"""
def __init__(self, **kwargs):
"""Args and parameters same as Integer."""Date and Time Fields
Date and datetime fields with format support and timezone handling.
class Date:
"""
Date/datetime field with format support.
"""
def __init__(self, format=None, **kwargs):
"""
Args:
format (str or list, optional): Date format(s) to accept
**kwargs: Date field parameters
Parameters:
boost (float): Field boost for relevance scoring
doc_values (bool): Store doc values for aggregations/sorting
ignore_malformed (bool): Ignore malformed values
index (bool): Index this field for search (default: True)
meta (dict): Metadata about the field
null_value (str): Value to use for null values
store (bool): Store field value separately
locale (str): Locale for parsing dates
"""
class DateNanos:
"""
Date field with nanosecond precision.
"""
def __init__(self, format=None, **kwargs):
"""Args and parameters same as Date."""Boolean Field
Boolean field for true/false values.
class Boolean:
"""
Boolean field for true/false values.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Boolean field parameters
Parameters:
boost (float): Field boost for relevance scoring
doc_values (bool): Store doc values for aggregations/sorting
index (bool): Index this field for search (default: True)
meta (dict): Metadata about the field
null_value (bool): Value to use for null values
store (bool): Store field value separately
"""Binary Field
Binary data field for storing binary content.
class Binary:
"""
Binary data field.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Binary field parameters
Parameters:
doc_values (bool): Store doc values (default: False)
store (bool): Store field value separately
"""Object and Nested Fields
Fields for structured data and nested objects.
class Object:
"""
Object field for structured data.
"""
def __init__(self, properties=None, **kwargs):
"""
Args:
properties (dict, optional): Object properties mapping
**kwargs: Object field parameters
Parameters:
dynamic (bool or str): Dynamic mapping behavior
enabled (bool): Enable object field (default: True)
include_in_all (bool): Include in _all field (deprecated)
"""
class Nested:
"""
Nested object field with independent query context.
"""
def __init__(self, properties=None, **kwargs):
"""
Args:
properties (dict, optional): Nested object properties
**kwargs: Nested field parameters
Parameters:
dynamic (bool or str): Dynamic mapping behavior
enabled (bool): Enable nested field (default: True)
include_in_parent (bool): Copy values to parent document
include_in_root (bool): Copy values to root document
"""
class Flattened:
"""
Flattened object field for dynamic mappings.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Flattened field parameters
Parameters:
boost (float): Field boost for relevance scoring
depth_limit (int): Maximum depth for object flattening
doc_values (bool): Store doc values for aggregations/sorting
eager_global_ordinals (bool): Load global ordinals eagerly
ignore_above (int): Ignore strings longer than this value
index (bool): Index this field for search (default: True)
index_options (str): Index options
null_value (str): Value to use for null values
similarity (str): Similarity algorithm to use
split_queries_on_whitespace (bool): Split queries on whitespace
"""Geographic Fields
Fields for geographic data and spatial queries.
class GeoPoint:
"""
Geographic point field for lat/lon coordinates.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: GeoPoint field parameters
Parameters:
ignore_malformed (bool): Ignore malformed geo values
ignore_z_value (bool): Ignore z coordinate values
null_value (dict): Value to use for null values
"""
class GeoShape:
"""
Geographic shape field for complex geometries.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: GeoShape field parameters
Parameters:
tree (str): Tree implementation ('geohash' or 'quadtree')
precision (str): Tree precision
tree_levels (int): Number of tree levels
strategy (str): Strategy for indexing shapes
distance_error_pct (float): Distance error percentage
orientation (str): Polygon orientation
points_only (bool): Only index point shapes
ignore_malformed (bool): Ignore malformed shapes
ignore_z_value (bool): Ignore z coordinate values
coerce (bool): Coerce shape values
"""Specialized Fields
Specialized fields for specific use cases.
class Ip:
"""
IPv4/IPv6 address field.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: IP field parameters
Parameters:
boost (float): Field boost for relevance scoring
doc_values (bool): Store doc values for aggregations/sorting
ignore_malformed (bool): Ignore malformed IP addresses
index (bool): Index this field for search (default: True)
null_value (str): Value to use for null values
store (bool): Store field value separately
"""
class Completion:
"""
Auto-completion/suggestion field.
"""
def __init__(self, analyzer=None, search_analyzer=None, **kwargs):
"""
Args:
analyzer (str, optional): Analyzer for indexing
search_analyzer (str, optional): Analyzer for searching
**kwargs: Completion field parameters
Parameters:
contexts (list): Context configurations
max_input_length (int): Maximum input length
preserve_separators (bool): Preserve separators
preserve_position_increments (bool): Preserve position increments
"""
class TokenCount:
"""
Count of tokens in analyzed text.
"""
def __init__(self, analyzer, **kwargs):
"""
Args:
analyzer (str): Analyzer to use for tokenization
**kwargs: Additional parameters same as Integer
"""
class Percolator:
"""
Field for storing query definitions.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Percolator field parameters
"""
class Join:
"""
Parent-child relationship field.
"""
def __init__(self, relations, **kwargs):
"""
Args:
relations (dict): Parent-child relationship mapping
**kwargs: Join field parameters
Parameters:
eager_global_ordinals (bool): Load global ordinals eagerly
"""Range Fields
Fields for storing numeric and date ranges.
class IntegerRange:
"""
Range of integer values.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Range field parameters
Parameters:
boost (float): Field boost for relevance scoring
coerce (bool): Coerce range values
doc_values (bool): Store doc values for aggregations/sorting
index (bool): Index this field for search (default: True)
store (bool): Store field value separately
"""
class FloatRange:
"""
Range of float values.
"""
def __init__(self, **kwargs):
"""Args and parameters same as IntegerRange."""
class LongRange:
"""
Range of long values.
"""
def __init__(self, **kwargs):
"""Args and parameters same as IntegerRange."""
class DoubleRange:
"""
Range of double values.
"""
def __init__(self, **kwargs):
"""Args and parameters same as IntegerRange."""
class DateRange:
"""
Range of date values.
"""
def __init__(self, format=None, **kwargs):
"""
Args:
format (str or list, optional): Date format(s)
**kwargs: Additional parameters same as IntegerRange
"""
class IpRange:
"""
Range of IP addresses.
"""
def __init__(self, **kwargs):
"""Args and parameters same as IntegerRange."""Vector Fields
Fields for vector similarity search and machine learning.
class DenseVector:
"""
Dense vector field for vector similarity search.
"""
def __init__(self, dims, **kwargs):
"""
Args:
dims (int): Vector dimensionality
**kwargs: Dense vector field parameters
Parameters:
similarity (str): Similarity function ('cosine', 'dot_product', 'l2_norm')
index (bool): Index vectors for search (default: True)
index_options (dict): Vector index options
"""
class SparseVector:
"""
Sparse vector field (deprecated in favor of dense_vector).
"""
class RankFeature:
"""
Numeric field for boosting query scores.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Rank feature field parameters
Parameters:
positive_score_impact (bool): Whether higher values increase score
"""
class RankFeatures:
"""
Multiple numeric fields for boosting query scores.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Rank features field parameters
Parameters:
positive_score_impact (bool): Whether higher values increase score
"""Search-Optimized Fields
Fields optimized for specific search patterns.
class SearchAsYouType:
"""
Field optimized for search-as-you-type functionality.
"""
def __init__(self, analyzer=None, search_analyzer=None, **kwargs):
"""
Args:
analyzer (str, optional): Analyzer for indexing
search_analyzer (str, optional): Analyzer for searching
**kwargs: Search-as-you-type field parameters
Parameters:
max_shingle_size (int): Maximum shingle size
index (bool): Index this field for search (default: True)
index_options (str): Index options
norms (bool): Store length normalization factors
store (bool): Store field value separately
similarity (str): Similarity algorithm to use
term_vector (str): Term vector storage options
"""Histogram Field
Aggregated numeric histogram data field.
class Histogram:
"""
Pre-aggregated numeric histogram data.
"""
def __init__(self, **kwargs):
"""
Args:
**kwargs: Histogram field parameters
Parameters:
ignore_malformed (bool): Ignore malformed histogram values
"""Usage Examples
Basic Field Definitions
from elasticsearch_dsl import Document, Text, Keyword, Date, Integer, Boolean
class BlogPost(Document):
# Text field with analyzer
title = Text(analyzer='snowball')
# Text field with multi-field
content = Text(
analyzer='standard',
fields={
'raw': Keyword(),
'english': Text(analyzer='english')
}
)
# Keyword field with ignore_above
author = Keyword(ignore_above=256)
# Date field with custom format
published_date = Date(format='yyyy-MM-dd')
# Numeric fields
view_count = Integer(null_value=0)
featured = Boolean()
class Index:
name = 'blog_posts'Nested and Object Fields
from elasticsearch_dsl import Document, Object, Nested, Text, Keyword, Date
class User(InnerDoc):
name = Text()
email = Keyword()
class Comment(InnerDoc):
author = Object(User)
content = Text()
created_at = Date()
likes = Integer()
class Article(Document):
title = Text()
# Single nested object
author = Object(User)
# Array of nested objects
comments = Nested(Comment)
# Nested with custom properties
metadata = Object(
properties={
'tags': Keyword(),
'category': Keyword(),
'priority': Integer()
}
)
class Index:
name = 'articles'Geographic Fields
from elasticsearch_dsl import Document, Text, GeoPoint, GeoShape
class Location(Document):
name = Text()
# Geographic point
coordinates = GeoPoint()
# Geographic shape
boundary = GeoShape()
class Index:
name = 'locations'
# Usage
location = Location(
name='Central Park',
coordinates={'lat': 40.785091, 'lon': -73.968285},
boundary={
'type': 'polygon',
'coordinates': [[
[-73.958, 40.800],
[-73.958, 40.770],
[-73.980, 40.770],
[-73.980, 40.800],
[-73.958, 40.800]
]]
}
)Advanced Field Configurations
from elasticsearch_dsl import Document, Text, Keyword, Completion, Join
class Product(Document):
# Text field with advanced options
name = Text(
analyzer='standard',
search_analyzer='search_time_analyzer',
boost=2.0,
fields={
'suggest': Completion(),
'raw': Keyword()
}
)
# Completion field for suggestions
suggest = Completion(
analyzer='simple',
contexts=[
{
'name': 'category',
'type': 'category',
'path': 'category'
}
]
)
# Join field for parent-child
relationship = Join(
relations={
'product': 'variant',
'variant': 'review'
}
)
class Index:
name = 'products'Vector Fields for Similarity Search
from elasticsearch_dsl import Document, Text, DenseVector, RankFeature
class Document(Document):
title = Text()
content = Text()
# Dense vector for semantic search
content_vector = DenseVector(
dims=768,
similarity='cosine'
)
# Rank features for boosting
quality_score = RankFeature(positive_score_impact=True)
recency_score = RankFeature(positive_score_impact=True)
class Index:
name = 'semantic_documents'Install with Tessl CLI
npx tessl i tessl/pypi-elasticsearch-dsl