Orchardcore Elasticsearch

Orchard Core Elasticsearch - Prompt Templates

Configure Elasticsearch

You are an Orchard Core expert. Generate code and configuration for Elasticsearch-based search in Orchard Core.

Guidelines

• Enable OrchardCore.Elasticsearch to manage Elasticsearch indices.
• Configure the Elasticsearch connection in appsettings.json under the OrchardCore_Elasticsearch section.
• Use the CreateOrUpdateIndexProfile recipe step to create indexes (preferred over the obsolete ElasticIndexSettings step).
• Use the ResetIndex recipe step to restart indexing without deleting entries (preferred over the obsolete elastic-index-reset step).
• Use the RebuildIndex recipe step to delete and recreate indexes (preferred over the obsolete elastic-index-rebuild step).
• Elasticsearch uses the Elasticsearch Query DSL for queries.
• Elasticsearch automatically maps string fields to both text and keyword types.
• Supported connection types: SingleNodeConnectionPool, CloudConnectionPool, StaticConnectionPool, SniffingConnectionPool, StickyConnectionPool.
• Supported authentication types: Basic, ApiKey, Base64ApiKey, KeyIdAndKey.
• Custom analyzers and token filters are defined in appsettings.json.
• Both Lucene and Elasticsearch modules can be enabled simultaneously.
• All recipe JSON must be wrapped in { "steps": [...] }.
• All C# classes must use the sealed modifier.

Enabling Elasticsearch Features

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "OrchardCore.Search",
        "OrchardCore.Elasticsearch",
        "OrchardCore.Indexing"
      ],
      "disable": []
    }
  ]
}

Elasticsearch Connection Configuration

Configure the connection in appsettings.json:

{
  "OrchardCore_Elasticsearch": {
    "ConnectionType": "SingleNodeConnectionPool",
    "Url": "http://localhost",
    "Ports": [9200],
    "AuthenticationType": "Basic",
    "Username": "admin",
    "Password": "admin",
    "CertificateFingerprint": "",
    "EnableDebugMode": false,
    "EnableHttpCompression": true,
    "IndexPrefix": "",
    "Analyzers": {
      "standard": {
        "type": "standard"
      }
    }
  }
}

Docker Deployment

For local development, deploy Elasticsearch with Docker Compose.

WSL2 prerequisite — set vm.max_map_count in %userprofile%\.wslconfig:

[wsl2]
kernelCommandLine = "sysctl.vm.max_map_count=262144"

Then restart WSL: wsl --shutdown

Creating an Elasticsearch Index Profile (Recommended)

{
  "steps": [
    {
      "name": "CreateOrUpdateIndexProfile",
      "indexes": [
        {
          "Name": "BlogPostsES",
          "IndexName": "blogposts",
          "ProviderName": "Elasticsearch",
          "Type": "Content",
          "Properties": {
            "ContentIndexMetadata": {
              "IndexLatest": false,
              "IndexedContentTypes": ["BlogPost"],
              "Culture": "any"
            },
            "ElasticsearchIndexMetadata": {
              "AnalyzerName": "standard",
              "StoreSourceData": true
            },
            "ElasticsearchDefaultQueryMetadata": {
              "QueryAnalyzerName": "standard",
              "SearchType": "",
              "DefaultQuery": "",
              "DefaultSearchFields": [
                "Content.ContentItem.FullText"
              ]
            }
          }
        }
      ]
    }
  ]
}

Legacy Index Creation (Obsolete)

{
  "steps": [
    {
      "name": "ElasticIndexSettings",
      "Indices": [
        {
          "Search": {
            "AnalyzerName": "standard",
            "IndexLatest": false,
            "IndexedContentTypes": [
              "Article",
              "BlogPost"
            ]
          }
        }
      ]
    }
  ]
}

Reset Elasticsearch Index

{
  "steps": [
    {
      "name": "ResetIndex",
      "indexNames": [
        "BlogPostsES"
      ]
    }
  ]
}

Rebuild Elasticsearch Index

{
  "steps": [
    {
      "name": "RebuildIndex",
      "indexNames": [
        "BlogPostsES"
      ]
    }
  ]
}

Creating an Elasticsearch Query via Recipe

{
  "steps": [
    {
      "name": "Queries",
      "Source": "Elasticsearch",
      "Name": "RecentBlogPosts",
      "Index": "Search",
      "Template": "{ \"query\": { \"match_all\": {} }, \"size\": 10 }",
      "ReturnContentItems": true
    }
  ]
}

Configuring Analyzers

Define built-in and custom analyzers in appsettings.json:

{
  "OrchardCore_Elasticsearch": {
    "Analyzers": {
      "standard": {
        "type": "standard"
      },
      "stop": {
        "type": "stop",
        "stopwords": ["a", "the", "and", "or"]
      },
      "english_analyzer": {
        "type": "custom",
        "tokenizer": "standard",
        "filter": ["lowercase", "stop"],
        "char_filter": ["html_strip"]
      }
    }
  }
}

Configuring Token Filters

Define custom token filters in appsettings.json and reference them from analyzers:

{
  "OrchardCore_Elasticsearch": {
    "TokenFilters": {
      "english_stop": {
        "type": "stop",
        "stopwords": "_english_"
      }
    },
    "Analyzers": {
      "my_new_analyzer": {
        "type": "custom",
        "tokenizer": "standard",
        "filter": ["english_stop"]
      }
    }
  }
}

Custom Query with Search Highlights

When using "custom" search type, define a query with highlighting using the Liquid {{ term }} placeholder:

{
  "query": {
    "multi_match": {
      "fields": ["Content.ContentItem.FullText"],
      "query": "{{ term }}",
      "fuzziness": "AUTO"
    }
  },
  "highlight": {
    "pre_tags": ["<span style='background-color: #FFF3CD;'>"],
    "post_tags": ["</span>"],
    "fields": {
      "Content.ContentItem.FullText": {
        "fragment_size": 150,
        "number_of_fragments": 3
      }
    }
  }
}

Highlight requests require StoreSourceData to be enabled on the index.

Web APIs

api/elasticsearch/content — Executes a query and returns content items.

Verbs: POST and GET

api/elasticsearch/documents — Executes a query and returns Elasticsearch documents (stored fields only).

Same parameters as api/elasticsearch/content.

Returning Specific Fields

Elasticsearch can return specific fields instead of full source:

{
  "query": {
    "match_all": {}
  },
  "fields": [
    "ContentItemId.keyword",
    "ContentItemVersionId.keyword"
  ],
  "_source": false
}

Indexing Custom Data

Register a custom indexing source in Startup.cs:

using OrchardCore.Modules;

namespace MyModule;

[Feature("MyModule.CustomElasticsearchIndex")]
public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddElasticsearchIndexingSource("CustomSource", o =>
        {
            o.DisplayName = S["Custom Source"];
            o.Description = S["Create an Elasticsearch index based on a custom data source."];
        });
    }
}

Elasticsearch vs Lucene Field Mapping

Elasticsearch automatically maps string fields to both text and keyword types. Lucene uses explicit StringField (keyword) and TextField (text) types.

Adapt queries when switching between Lucene and Elasticsearch — field types may differ for the same field name.