ravendb.ravendb.index module – Manage RavenDB indexes

Note

This module is part of the ravendb.ravendb collection (version 1.0.4).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ravendb.ravendb. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: ravendb.ravendb.index.

New in ravendb.ravendb 1.0.0

Synopsis

• Create, delete, update, or apply operational modes to RavenDB indexes.

• Supports both single-map and multi-map index definitions (with optional reduce).

• Supports check mode to simulate changes without applying them.

• Can reconcile per-index configuration via index_configuration.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 3.9

• ravendb python client

• ASP.NET Core Runtime

• requests

• Role ravendb.ravendb.ravendb_python_client_prerequisites must be installed before using this module.

Parameters

Parameter	Comments
ca_cert_path string	Path to a trusted CA certificate file to verify the RavenDB server’s certificate.
certificate_path string	Path to a client certificate (PEM format) for secured communication.
cluster_wide boolean	Whether to apply enable/disable operations cluster-wide. Choices: false ← (default) true
database_name string / required	Name of the database. Must be a valid name containing only letters, numbers, dashes, and underscores.
index_configuration dictionary	Per-index configuration key/value pairs to reconcile. Keys and values are normalized to strings and compared against the current index definition’s configuration. If differences exist, the module updates the definition with the merged configuration. Default: {}
index_definition dictionary	Dictionary defining the index (map list and optional reduce string). Required when creating a new index. When present for an existing index, differences are applied idempotently.
index_name string / required	Name of the index to create, delete, or modify. Must consist only of letters, numbers, dashes, and underscores.
mode string	Operational mode to apply to an existing index (one of enable/disable/pause/resume/reset). If the index does not exist and only mode is provided, the task fails with guidance to create it first. Choices: "resumed" "paused" "enabled" "disabled" "reset"
state string	Desired state of the index. If present, the index will be created if it does not exist, and the definition/configuration will be reconciled. If absent, the index will be deleted if it exists. If omitted (null), the module operates in “reconcile” mode on existing indexes only (definition, configuration, and/or mode). If the index does not exist and only mode is provided, the task fails with guidance to use state=present. Choices: "present" "absent"
url string / required	URL of the RavenDB server. Must include the scheme (http or https), hostname, and port.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target. If not supported, the action will be skipped.

Notes

Note

• The role ravendb.ravendb.ravendb_python_client_prerequisites must be applied before using this module.

• Requires the ASP.NET Core Runtime to be installed on the target system.

See Also

See also

RavenDB documentation

Official RavenDB documentation

Examples

- name: Create a RavenDB index with map and reduce
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "UsersByName"
    index_definition:
      map:
        - "from c in docs.Users select new { c.name, count = 5 }"
      reduce: >
        from result in results
        group result by result.name
        into g
        select new
        {
          name = g.Key,
          count = g.Sum(x => x.count)
        }
    state: present

- name: Create a RavenDB multi-map index
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "UsersAndOrdersByName"
    index_definition:
      map:
        - "from c in docs.Users select new { Name = c.name, UserCount = 1, OrderCount = 0, TotalCount = 1 }"
        - "from o in docs.Orders select new { Name = o.customer, UserCount = 0, OrderCount = 1, TotalCount = 1 }"
      reduce: >
        from result in results
        group result by result.Name
        into g
        select new
        {
          Name = g.Key,
          UserCount = g.Sum(x => x.UserCount),
          OrderCount = g.Sum(x => x.OrderCount),
          TotalCount = g.Sum(x => x.TotalCount)
        }
    state: present

- name: Reconcile per-index configuration (idempotent)
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "UsersByName"
    index_configuration:
      Indexing.MapBatchSize: "128"

- name: Disable a RavenDB index (cluster-wide)
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "Orders/ByCompany"
    mode: disabled
    cluster_wide: true

- name: Pause a RavenDB index (check mode)
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "Orders/ByCompany"
    mode: paused
  check_mode: yes

- name: Update an existing RavenDB index definition (idempotent update)
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "UsersByName"
    index_definition:
      map:
        - "from c in docs.Users select new { c.name, count = 13 }"
      reduce: >
        from result in results
        group result by result.name
        into g
        select new
        {
          name = g.Key,
          count = g.Sum(x => x.count)
        }
    state: present

- name: Delete a RavenDB index
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "UsersByName"
    state: absent

- name: Create index with rolling deployment
  ravendb.ravendb.index:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    index_name: "Orders/ByCompany"
    state: present
    index_definition:
      map:
        - "from o in docs.Orders select new { o.Company }"
      deployment_mode: rolling

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed boolean	Indicates if any change was made (or would have been made in check mode). Returned: always Sample: true
msg string added in ravendb.ravendb 1.0.0	Human-readable message describing the result or error. Returned: always Sample: "Index 'Products_ByName' created successfully."

Authors

• Omer Ratsaby (@thegoldenplatypus)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)