Put Indexes Operation
-
There are a few ways to create and deploy indexes in a database.
-
This page describes deploying a static-index using the
PutIndexesOperation
Operation.
For a general description of Operations see what are operations. -
In this page:
Ways to deploy indexes - short summary
Static index:
There are a few ways to deploy a static-index from the Client API:
- Call
execute()
on a specific index instance - Call
IndexCreation.create_indexes()
to deploy multiple indexes - Execute
PutIndexesOperation
maintenance operation on the Document Store - see below - Learn more in static indexes
Auto index:
- An auto-index is created by the server when making a filtering query that doesn't specify which index to use
- Learn more in auto indexes
Put indexes operation with IndexDefinition
Using PutIndexesOperation
with IndexDefinition allows the following:
- Choosing any name for the index.
- Setting low-level properties available in IndexDefinition.
# Create an index definition
index_definition = IndexDefinition(
# Name is mandatory, can use any string
name="OrdersByTotal",
# Define the index Map functions, string format
# A single string for a map-index, multiple strings for a multi-map-index
maps={
"""
// Define the collection that will be indexed:
from order in docs.Orders
// Define the index-entry:
select new
{
// Define the index-fields within each index-entry:
Employee = order.Employee,
Company = order.Company,
Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount))
}
"""
},
# reduce = ...
# Can provide other index definitions available on the IndexDefinition class
# Override the default values, e.g.:
deployment_mode=IndexDeploymentMode.ROLLING,
priority=IndexPriority.HIGH,
configuration={"Indexing.IndexMissingFieldsAsNull": "true"},
# See all available properties in syntax below
)
# Define the put indexes operation, pass the index definition
# Note: multiple index definitions can be passed, see syntax below
put_indexes_op = PutIndexesOperation(index_definition)
# Execute the operation by passing it to maintenance.send
store.maintenance.send(put_indexes_op)
# Create an index definition
index_definition = IndexDefinition(
# Name is mandatory, can use any string
name="OrdersByTotal",
# Define the index map functions, string format
# A single string for a map-index, multiple strings for a multimap index
maps={
"""
map('Orders', function(order) {
return {
Employee: order.Employee,
Company: order.Company,
Total: order.Lines.reduce(function(sum, l) {
return sum + (l.Quantity * l.PricePerUnit) * (1 - l.Discount);
}, 0)
};
});
"""
},
# reduce = ...,
# Can provide other index definitions available on the IndexDefinition class
# Override the default values, e.g.:
deployment_mode=IndexDeploymentMode.ROLLING,
priority=IndexPriority.HIGH,
configuration={"Indexing.IndexMissingFieldsAsNull": "true"},
# See all available properties in syntax below
)
# Define the put indexes operation, pass the index definition
# Note: multiple index definitions can be passed, see syntax below
put_indexes_op = PutIndexesOperation(index_definition)
# Execute the operation by passing it to Maintenance.Send
store.maintenance.send(put_indexes_op)
Put indexes operation with IndexDefinitionBuilder
-
Using
PutIndexesOperation
with an IndexDefinition created from an IndexDefinitionBuilder allows setting low-level properties available in IndexDefinitionBuilder. -
Note that only map or map-reduce indexes can be generated by the IndexDefinitionBuilder.
To generate multi-map indexes, use the above IndexDefinition option.
# Create an index definition builder
builder = IndexDefinitionBuilder()
builder.map = """
// Define the collection that will be indexed:
from order in docs.Orders
// Define the index-entry:
select new
{
// Define the index-fields within each index-entry:
Employee = order.Employee,
Company = order.Company,
Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount))
}
"""
# Can provide other properties available on the IndexDefinitionBuilder class, e.g.:
builder.deployment_mode = IndexDeploymentMode.ROLLING
builder.priority = IndexPriority.HIGH
# builder.reduce = ..., etc.
# Generate index definition from builder
# Pass the conventions, needed for building the maps property
builder.to_index_definition(store.conventions)
# Optionally, set the index name, can use any string
# If not provided then default name from builder is used, e.g.: "IndexDefinitionBuildersOfOrders"
index_definition.name = "OrdersByTotal"
# Define the put indexes operation, pass the index definition
# Note: multiple index definitions can be passed, see syntax below
put_indexes_op = PutIndexesOperation(index_definition)
# Execute the operation by passing it to Maintenance.Send
store.maintenance.send(put_indexes_op)
Syntax
class PutIndexesOperation(MaintenanceOperation):
def __init__(self, *indexes_to_add: IndexDefinition): ...
Parameters | Type | Description |
---|---|---|
*indexes_to_add | IndexDefinition |
Definitions of indexes to deploy |
IndexDefinition parameter |
Type | Description |
---|---|---|
name | str |
Name of the index, a unique identifier |
maps | Set[str] |
All the map functions for the index |
reduce | str |
The index reduce function |
deployment_mode | IndexDeploymentMode |
Deployment mode (PARALLEL, ROLLING) |
state | IndexState |
State of index (NORMAL, DISABLED, IDLE, ERROR) |
priority | IndexPriority |
Priority of index (LOW, NORMAL, HIGH) |
lock_mode | IndexLockMode |
Lock mode of index (UNLOCK, LOCKED_IGNORE, LOCKED_ERROR) |
fields | Dict[str, IndexFieldOptions] |
IndexFieldOptions per index field |
additional_sources | Dict[str, str] |
Additional code files to be compiled with this index |
additional_assemblies | Set[AdditionalAssembly] |
Additional assemblies that are referenced |
configuration | IndexConfiguration |
Can override indexing configuration by setting this dictionary |
output_reduce_to_collection | str |
A collection name for saving the reduce results as documents |
reduce_output_index | int |
This number will be part of the reduce results documents IDs |
pattern_for_output_reduce_to_collection_references | str |
Pattern for documents IDs which reference IDs of reduce results documents |
pattern_references_collection_name | str |
A collection name for the reference documents created based on provided pattern |
store.maintenance.send(put_indexes_op) return value |
Description |
---|---|
List[PutIndexResult] |
List of PutIndexResult per index |
PutIndexResult parameter |
Type | Description |
---|---|---|
index | str |
Name of the index that was added |
raft_command_index | int |
Index of raft command that was executed |