0
# Field Types
1
2
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.
3
4
## Capabilities
5
6
### Text Fields
7
8
Full-text search fields with analyzer support for natural language processing and search.
9
10
```python { .api }
11
class Text:
12
"""
13
Full-text field for analyzed text content.
14
"""
15
def __init__(self, analyzer=None, search_analyzer=None, fields=None, **kwargs):
16
"""
17
Args:
18
analyzer (str, optional): Analyzer for indexing
19
search_analyzer (str, optional): Analyzer for searching
20
fields (dict, optional): Multi-fields mapping
21
**kwargs: Additional text field parameters
22
23
Parameters:
24
boost (float): Field boost for relevance scoring
25
eager_global_ordinals (bool): Load global ordinals eagerly
26
fielddata (bool): Enable fielddata for aggregations/sorting
27
fielddata_frequency_filter (dict): Fielddata frequency filtering
28
index (bool): Index this field for search (default: True)
29
index_options (str): Index options ('docs', 'freqs', 'positions', 'offsets')
30
index_prefixes (dict): Index prefixes configuration
31
index_phrases (bool): Index two-term word combinations
32
norms (bool): Store length normalization factors
33
position_increment_gap (int): Gap between array elements
34
store (bool): Store field value separately
35
search_quote_analyzer (str): Analyzer for quoted searches
36
similarity (str): Similarity algorithm to use
37
term_vector (str): Term vector storage options
38
"""
39
40
class Keyword:
41
"""
42
Exact-value field for filtering, sorting, and aggregations.
43
"""
44
def __init__(self, **kwargs):
45
"""
46
Args:
47
**kwargs: Keyword field parameters
48
49
Parameters:
50
boost (float): Field boost for relevance scoring
51
doc_values (bool): Store doc values for aggregations/sorting
52
eager_global_ordinals (bool): Load global ordinals eagerly
53
fields (dict): Multi-fields mapping
54
ignore_above (int): Ignore strings longer than this value
55
index (bool): Index this field for search (default: True)
56
index_options (str): Index options
57
norms (bool): Store length normalization factors
58
null_value (str): Value to use for null values
59
store (bool): Store field value separately
60
similarity (str): Similarity algorithm to use
61
normalizer (str): Normalizer to apply
62
split_queries_on_whitespace (bool): Split queries on whitespace
63
"""
64
```
65
66
### Numeric Fields
67
68
Numeric field types for mathematical operations, range queries, and aggregations.
69
70
```python { .api }
71
class Integer:
72
"""
73
32-bit signed integer field.
74
"""
75
def __init__(self, **kwargs):
76
"""
77
Args:
78
**kwargs: Integer field parameters
79
80
Parameters:
81
boost (float): Field boost for relevance scoring
82
doc_values (bool): Store doc values for aggregations/sorting
83
ignore_malformed (bool): Ignore malformed values
84
index (bool): Index this field for search (default: True)
85
meta (dict): Metadata about the field
86
null_value (int): Value to use for null values
87
store (bool): Store field value separately
88
"""
89
90
class Long:
91
"""
92
64-bit signed integer field.
93
"""
94
def __init__(self, **kwargs):
95
"""Args and parameters same as Integer."""
96
97
class Float:
98
"""
99
32-bit floating point field.
100
"""
101
def __init__(self, **kwargs):
102
"""Args and parameters same as Integer."""
103
104
class Double:
105
"""
106
64-bit floating point field.
107
"""
108
def __init__(self, **kwargs):
109
"""Args and parameters same as Integer."""
110
111
class Short:
112
"""
113
16-bit signed integer field.
114
"""
115
def __init__(self, **kwargs):
116
"""Args and parameters same as Integer."""
117
118
class Byte:
119
"""
120
8-bit signed integer field.
121
"""
122
def __init__(self, **kwargs):
123
"""Args and parameters same as Integer."""
124
125
class HalfFloat:
126
"""
127
16-bit floating point field.
128
"""
129
def __init__(self, **kwargs):
130
"""Args and parameters same as Integer."""
131
132
class ScaledFloat:
133
"""
134
Floating point backed by long with scaling factor.
135
"""
136
def __init__(self, scaling_factor, **kwargs):
137
"""
138
Args:
139
scaling_factor (int): Scaling factor for the value
140
**kwargs: Additional parameters same as Integer
141
"""
142
143
class UnsignedLong:
144
"""
145
64-bit unsigned integer field.
146
"""
147
def __init__(self, **kwargs):
148
"""Args and parameters same as Integer."""
149
```
150
151
### Date and Time Fields
152
153
Date and datetime fields with format support and timezone handling.
154
155
```python { .api }
156
class Date:
157
"""
158
Date/datetime field with format support.
159
"""
160
def __init__(self, format=None, **kwargs):
161
"""
162
Args:
163
format (str or list, optional): Date format(s) to accept
164
**kwargs: Date field parameters
165
166
Parameters:
167
boost (float): Field boost for relevance scoring
168
doc_values (bool): Store doc values for aggregations/sorting
169
ignore_malformed (bool): Ignore malformed values
170
index (bool): Index this field for search (default: True)
171
meta (dict): Metadata about the field
172
null_value (str): Value to use for null values
173
store (bool): Store field value separately
174
locale (str): Locale for parsing dates
175
"""
176
177
class DateNanos:
178
"""
179
Date field with nanosecond precision.
180
"""
181
def __init__(self, format=None, **kwargs):
182
"""Args and parameters same as Date."""
183
```
184
185
### Boolean Field
186
187
Boolean field for true/false values.
188
189
```python { .api }
190
class Boolean:
191
"""
192
Boolean field for true/false values.
193
"""
194
def __init__(self, **kwargs):
195
"""
196
Args:
197
**kwargs: Boolean field parameters
198
199
Parameters:
200
boost (float): Field boost for relevance scoring
201
doc_values (bool): Store doc values for aggregations/sorting
202
index (bool): Index this field for search (default: True)
203
meta (dict): Metadata about the field
204
null_value (bool): Value to use for null values
205
store (bool): Store field value separately
206
"""
207
```
208
209
### Binary Field
210
211
Binary data field for storing binary content.
212
213
```python { .api }
214
class Binary:
215
"""
216
Binary data field.
217
"""
218
def __init__(self, **kwargs):
219
"""
220
Args:
221
**kwargs: Binary field parameters
222
223
Parameters:
224
doc_values (bool): Store doc values (default: False)
225
store (bool): Store field value separately
226
"""
227
```
228
229
### Object and Nested Fields
230
231
Fields for structured data and nested objects.
232
233
```python { .api }
234
class Object:
235
"""
236
Object field for structured data.
237
"""
238
def __init__(self, properties=None, **kwargs):
239
"""
240
Args:
241
properties (dict, optional): Object properties mapping
242
**kwargs: Object field parameters
243
244
Parameters:
245
dynamic (bool or str): Dynamic mapping behavior
246
enabled (bool): Enable object field (default: True)
247
include_in_all (bool): Include in _all field (deprecated)
248
"""
249
250
class Nested:
251
"""
252
Nested object field with independent query context.
253
"""
254
def __init__(self, properties=None, **kwargs):
255
"""
256
Args:
257
properties (dict, optional): Nested object properties
258
**kwargs: Nested field parameters
259
260
Parameters:
261
dynamic (bool or str): Dynamic mapping behavior
262
enabled (bool): Enable nested field (default: True)
263
include_in_parent (bool): Copy values to parent document
264
include_in_root (bool): Copy values to root document
265
"""
266
267
class Flattened:
268
"""
269
Flattened object field for dynamic mappings.
270
"""
271
def __init__(self, **kwargs):
272
"""
273
Args:
274
**kwargs: Flattened field parameters
275
276
Parameters:
277
boost (float): Field boost for relevance scoring
278
depth_limit (int): Maximum depth for object flattening
279
doc_values (bool): Store doc values for aggregations/sorting
280
eager_global_ordinals (bool): Load global ordinals eagerly
281
ignore_above (int): Ignore strings longer than this value
282
index (bool): Index this field for search (default: True)
283
index_options (str): Index options
284
null_value (str): Value to use for null values
285
similarity (str): Similarity algorithm to use
286
split_queries_on_whitespace (bool): Split queries on whitespace
287
"""
288
```
289
290
### Geographic Fields
291
292
Fields for geographic data and spatial queries.
293
294
```python { .api }
295
class GeoPoint:
296
"""
297
Geographic point field for lat/lon coordinates.
298
"""
299
def __init__(self, **kwargs):
300
"""
301
Args:
302
**kwargs: GeoPoint field parameters
303
304
Parameters:
305
ignore_malformed (bool): Ignore malformed geo values
306
ignore_z_value (bool): Ignore z coordinate values
307
null_value (dict): Value to use for null values
308
"""
309
310
class GeoShape:
311
"""
312
Geographic shape field for complex geometries.
313
"""
314
def __init__(self, **kwargs):
315
"""
316
Args:
317
**kwargs: GeoShape field parameters
318
319
Parameters:
320
tree (str): Tree implementation ('geohash' or 'quadtree')
321
precision (str): Tree precision
322
tree_levels (int): Number of tree levels
323
strategy (str): Strategy for indexing shapes
324
distance_error_pct (float): Distance error percentage
325
orientation (str): Polygon orientation
326
points_only (bool): Only index point shapes
327
ignore_malformed (bool): Ignore malformed shapes
328
ignore_z_value (bool): Ignore z coordinate values
329
coerce (bool): Coerce shape values
330
"""
331
```
332
333
### Specialized Fields
334
335
Specialized fields for specific use cases.
336
337
```python { .api }
338
class Ip:
339
"""
340
IPv4/IPv6 address field.
341
"""
342
def __init__(self, **kwargs):
343
"""
344
Args:
345
**kwargs: IP field parameters
346
347
Parameters:
348
boost (float): Field boost for relevance scoring
349
doc_values (bool): Store doc values for aggregations/sorting
350
ignore_malformed (bool): Ignore malformed IP addresses
351
index (bool): Index this field for search (default: True)
352
null_value (str): Value to use for null values
353
store (bool): Store field value separately
354
"""
355
356
class Completion:
357
"""
358
Auto-completion/suggestion field.
359
"""
360
def __init__(self, analyzer=None, search_analyzer=None, **kwargs):
361
"""
362
Args:
363
analyzer (str, optional): Analyzer for indexing
364
search_analyzer (str, optional): Analyzer for searching
365
**kwargs: Completion field parameters
366
367
Parameters:
368
contexts (list): Context configurations
369
max_input_length (int): Maximum input length
370
preserve_separators (bool): Preserve separators
371
preserve_position_increments (bool): Preserve position increments
372
"""
373
374
class TokenCount:
375
"""
376
Count of tokens in analyzed text.
377
"""
378
def __init__(self, analyzer, **kwargs):
379
"""
380
Args:
381
analyzer (str): Analyzer to use for tokenization
382
**kwargs: Additional parameters same as Integer
383
"""
384
385
class Percolator:
386
"""
387
Field for storing query definitions.
388
"""
389
def __init__(self, **kwargs):
390
"""
391
Args:
392
**kwargs: Percolator field parameters
393
"""
394
395
class Join:
396
"""
397
Parent-child relationship field.
398
"""
399
def __init__(self, relations, **kwargs):
400
"""
401
Args:
402
relations (dict): Parent-child relationship mapping
403
**kwargs: Join field parameters
404
405
Parameters:
406
eager_global_ordinals (bool): Load global ordinals eagerly
407
"""
408
```
409
410
### Range Fields
411
412
Fields for storing numeric and date ranges.
413
414
```python { .api }
415
class IntegerRange:
416
"""
417
Range of integer values.
418
"""
419
def __init__(self, **kwargs):
420
"""
421
Args:
422
**kwargs: Range field parameters
423
424
Parameters:
425
boost (float): Field boost for relevance scoring
426
coerce (bool): Coerce range values
427
doc_values (bool): Store doc values for aggregations/sorting
428
index (bool): Index this field for search (default: True)
429
store (bool): Store field value separately
430
"""
431
432
class FloatRange:
433
"""
434
Range of float values.
435
"""
436
def __init__(self, **kwargs):
437
"""Args and parameters same as IntegerRange."""
438
439
class LongRange:
440
"""
441
Range of long values.
442
"""
443
def __init__(self, **kwargs):
444
"""Args and parameters same as IntegerRange."""
445
446
class DoubleRange:
447
"""
448
Range of double values.
449
"""
450
def __init__(self, **kwargs):
451
"""Args and parameters same as IntegerRange."""
452
453
class DateRange:
454
"""
455
Range of date values.
456
"""
457
def __init__(self, format=None, **kwargs):
458
"""
459
Args:
460
format (str or list, optional): Date format(s)
461
**kwargs: Additional parameters same as IntegerRange
462
"""
463
464
class IpRange:
465
"""
466
Range of IP addresses.
467
"""
468
def __init__(self, **kwargs):
469
"""Args and parameters same as IntegerRange."""
470
```
471
472
### Vector Fields
473
474
Fields for vector similarity search and machine learning.
475
476
```python { .api }
477
class DenseVector:
478
"""
479
Dense vector field for vector similarity search.
480
"""
481
def __init__(self, dims, **kwargs):
482
"""
483
Args:
484
dims (int): Vector dimensionality
485
**kwargs: Dense vector field parameters
486
487
Parameters:
488
similarity (str): Similarity function ('cosine', 'dot_product', 'l2_norm')
489
index (bool): Index vectors for search (default: True)
490
index_options (dict): Vector index options
491
"""
492
493
class SparseVector:
494
"""
495
Sparse vector field (deprecated in favor of dense_vector).
496
"""
497
498
class RankFeature:
499
"""
500
Numeric field for boosting query scores.
501
"""
502
def __init__(self, **kwargs):
503
"""
504
Args:
505
**kwargs: Rank feature field parameters
506
507
Parameters:
508
positive_score_impact (bool): Whether higher values increase score
509
"""
510
511
class RankFeatures:
512
"""
513
Multiple numeric fields for boosting query scores.
514
"""
515
def __init__(self, **kwargs):
516
"""
517
Args:
518
**kwargs: Rank features field parameters
519
520
Parameters:
521
positive_score_impact (bool): Whether higher values increase score
522
"""
523
```
524
525
### Search-Optimized Fields
526
527
Fields optimized for specific search patterns.
528
529
```python { .api }
530
class SearchAsYouType:
531
"""
532
Field optimized for search-as-you-type functionality.
533
"""
534
def __init__(self, analyzer=None, search_analyzer=None, **kwargs):
535
"""
536
Args:
537
analyzer (str, optional): Analyzer for indexing
538
search_analyzer (str, optional): Analyzer for searching
539
**kwargs: Search-as-you-type field parameters
540
541
Parameters:
542
max_shingle_size (int): Maximum shingle size
543
index (bool): Index this field for search (default: True)
544
index_options (str): Index options
545
norms (bool): Store length normalization factors
546
store (bool): Store field value separately
547
similarity (str): Similarity algorithm to use
548
term_vector (str): Term vector storage options
549
"""
550
```
551
552
### Histogram Field
553
554
Aggregated numeric histogram data field.
555
556
```python { .api }
557
class Histogram:
558
"""
559
Pre-aggregated numeric histogram data.
560
"""
561
def __init__(self, **kwargs):
562
"""
563
Args:
564
**kwargs: Histogram field parameters
565
566
Parameters:
567
ignore_malformed (bool): Ignore malformed histogram values
568
"""
569
```
570
571
## Usage Examples
572
573
### Basic Field Definitions
574
575
```python
576
from elasticsearch_dsl import Document, Text, Keyword, Date, Integer, Boolean
577
578
class BlogPost(Document):
579
# Text field with analyzer
580
title = Text(analyzer='snowball')
581
582
# Text field with multi-field
583
content = Text(
584
analyzer='standard',
585
fields={
586
'raw': Keyword(),
587
'english': Text(analyzer='english')
588
}
589
)
590
591
# Keyword field with ignore_above
592
author = Keyword(ignore_above=256)
593
594
# Date field with custom format
595
published_date = Date(format='yyyy-MM-dd')
596
597
# Numeric fields
598
view_count = Integer(null_value=0)
599
featured = Boolean()
600
601
class Index:
602
name = 'blog_posts'
603
```
604
605
### Nested and Object Fields
606
607
```python
608
from elasticsearch_dsl import Document, Object, Nested, Text, Keyword, Date
609
610
class User(InnerDoc):
611
name = Text()
612
email = Keyword()
613
614
class Comment(InnerDoc):
615
author = Object(User)
616
content = Text()
617
created_at = Date()
618
likes = Integer()
619
620
class Article(Document):
621
title = Text()
622
623
# Single nested object
624
author = Object(User)
625
626
# Array of nested objects
627
comments = Nested(Comment)
628
629
# Nested with custom properties
630
metadata = Object(
631
properties={
632
'tags': Keyword(),
633
'category': Keyword(),
634
'priority': Integer()
635
}
636
)
637
638
class Index:
639
name = 'articles'
640
```
641
642
### Geographic Fields
643
644
```python
645
from elasticsearch_dsl import Document, Text, GeoPoint, GeoShape
646
647
class Location(Document):
648
name = Text()
649
650
# Geographic point
651
coordinates = GeoPoint()
652
653
# Geographic shape
654
boundary = GeoShape()
655
656
class Index:
657
name = 'locations'
658
659
# Usage
660
location = Location(
661
name='Central Park',
662
coordinates={'lat': 40.785091, 'lon': -73.968285},
663
boundary={
664
'type': 'polygon',
665
'coordinates': [[
666
[-73.958, 40.800],
667
[-73.958, 40.770],
668
[-73.980, 40.770],
669
[-73.980, 40.800],
670
[-73.958, 40.800]
671
]]
672
}
673
)
674
```
675
676
### Advanced Field Configurations
677
678
```python
679
from elasticsearch_dsl import Document, Text, Keyword, Completion, Join
680
681
class Product(Document):
682
# Text field with advanced options
683
name = Text(
684
analyzer='standard',
685
search_analyzer='search_time_analyzer',
686
boost=2.0,
687
fields={
688
'suggest': Completion(),
689
'raw': Keyword()
690
}
691
)
692
693
# Completion field for suggestions
694
suggest = Completion(
695
analyzer='simple',
696
contexts=[
697
{
698
'name': 'category',
699
'type': 'category',
700
'path': 'category'
701
}
702
]
703
)
704
705
# Join field for parent-child
706
relationship = Join(
707
relations={
708
'product': 'variant',
709
'variant': 'review'
710
}
711
)
712
713
class Index:
714
name = 'products'
715
```
716
717
### Vector Fields for Similarity Search
718
719
```python
720
from elasticsearch_dsl import Document, Text, DenseVector, RankFeature
721
722
class Document(Document):
723
title = Text()
724
content = Text()
725
726
# Dense vector for semantic search
727
content_vector = DenseVector(
728
dims=768,
729
similarity='cosine'
730
)
731
732
# Rank features for boosting
733
quality_score = RankFeature(positive_score_impact=True)
734
recency_score = RankFeature(positive_score_impact=True)
735
736
class Index:
737
name = 'semantic_documents'
738
```