{"id":18073222,"url":"https://github.com/elastic/semantic-kernel-net","last_synced_at":"2025-03-28T15:33:02.375Z","repository":{"id":258314394,"uuid":"869973984","full_name":"elastic/semantic-kernel-net","owner":"elastic","description":"The official Elasticsearch .NET Vector Store Connector for Microsoft Semantic Kernel.","archived":false,"fork":false,"pushed_at":"2024-11-26T14:54:29.000Z","size":324,"stargazers_count":14,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-19T14:49:27.906Z","etag":null,"topics":["ai","connector","elasticsearch","semantic-kernel","vector-store"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elastic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-09T08:18:10.000Z","updated_at":"2025-03-04T20:30:41.000Z","dependencies_parsed_at":"2024-11-21T15:28:41.331Z","dependency_job_id":"3a5ffb85-fb3c-44e2-8025-d71ddcebd493","html_url":"https://github.com/elastic/semantic-kernel-net","commit_stats":null,"previous_names":["elastic/semantic-kernel-net"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsemantic-kernel-net","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsemantic-kernel-net/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsemantic-kernel-net/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsemantic-kernel-net/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elastic","download_url":"https://codeload.github.com/elastic/semantic-kernel-net/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246034268,"owners_count":20712851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","connector","elasticsearch","semantic-kernel","vector-store"],"created_at":"2024-10-31T10:05:38.572Z","updated_at":"2025-03-28T15:33:02.369Z","avatar_url":"https://github.com/elastic.png","language":"C#","readme":"\u003cimg align=\"right\" width=\"auto\" height=\"auto\" src=\"https://www.elastic.co/static-res/images/elastic-logo-200.png\"/\u003e\n\n# Elasticsearch connector for Microsoft Semantic Kernel\n\nRepository for `Elastic.SemanticKernel.Connectors.Elasticsearch` the official Elasticsearch [Vector Store Connector](https://learn.microsoft.com/en-us/semantic-kernel/concepts/vector-store-connectors/?pivots=programming-language-csharp) for\n[Microsoft Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/).\n\n## Introduction\n\n[Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) is an SDK that integrates Large Language Models (LLMs) like OpenAI, Azure OpenAI, and Hugging Face with conventional programming languages like C#, Python, and Java. Semantic Kernel achieves this by allowing you to define plugins that can be chained together in just a few lines of code.\n\nSemantic Kernel and .NET provides an abstraction for interacting with Vector Stores and a list of out-of-the-box connectors that implement these abstractions. Features include creating, listing and deleting collections of records, and uploading, retrieving and deleting records. The abstraction makes it easy to experiment with a free or locally hosted Vector Store and then switch to a service when needing to scale up.\n\nThis repository contains the official Elasticsearch Vector Store Connector implementation for Semantic Kernel.\n\n## Overview\n\nThe Elasticsearch Vector Store connector can be used to access and manage data in Elasticsearch. The connector has the following characteristics.\n\n| Feature Area                      | Support                                                                                                                          |\n|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------|\n| Collection maps to                | Elasticsearch index                                                                                                              |\n| Supported key property types      | string                                                                                                                           |\n| Supported data property types     | All types that are supported by System.Text.Json (etiher built-in or by using a custom converter)                                |\n| Supported vector property types   | \u003cul\u003e\u003cli\u003eReadOnlyMemory\\\u003cfloat\\\u003e\u003c/li\u003e\u003cli\u003eIEnumerable\\\u003cfloat\\\u003e\u003c/li\u003e\u003c/ul\u003e                                                           |\n| Supported index types             | \u003cul\u003e\u003cli\u003eHNSW (32, 8, or 4 bit)\u003c/li\u003e\u003cli\u003eFLAT (32, 8, or 4 bit)\u003c/li\u003e\u003c/ul\u003e                                                          |\n| Supported distance functions      | \u003cul\u003e\u003cli\u003eCosineSimilarity\u003c/li\u003e\u003cli\u003eDotProductSimilarity\u003c/li\u003e\u003cli\u003eEuclideanDistance\u003c/li\u003e\u003cli\u003eMaxInnerProduct\u003c/li\u003e\u003c/ul\u003e                |\n| Supports multiple vectors in a record | Yes                                                                                                                          |\n| IsFilterable supported?           | Yes                                                                                                                              |\n| IsFullTextSearchable supported?   | Yes                                                                                                                              |\n| StoragePropertyName supported?    | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping)                |\n\n## Getting Started\n\n### Setting up Elasticsearch\n\nThe simplest way to get set up with Elasticsearch is to create a managed deployment on Elastic Cloud. [Signup for a free trial](https://cloud.elastic.co/registration?onboarding_token=vectorsearch\u0026utm_source=semantickernel\u0026utm_content=documentation).\n\nIf you prefer to install and manage Elasticsearch yourself and run with authentication you can download the latest version from the Elastic \n[downloads page](https://www.elastic.co/downloads/elasticsearch).\n\nTo [run Elasticsearch locally](https://www.elastic.co/guide/en/elasticsearch/reference/current/run-elasticsearch-locally.html) for local development or testing run the `start-local` script with one command: \n\n```bash\ncurl -fsSL https://elastic.co/start-local | sh\n```\n\n### Using the Elasticsearch Vector Store Connector\n\nAdd the Elasticsearch Vector Store connector NuGet package to your project.\n\n```dotnetcli\ndotnet add package Elastic.SemanticKernel.Connectors.Elasticsearch --prerelease\n```\n\nYou can add the vector store to the dependency injection container available on the `KernelBuilder` or to the `IServiceCollection` dependency injection container using extension methods provided by Semantic Kernel.\n\n```csharp\nusing Microsoft.SemanticKernel;\nusing Elastic.Clients.Elasticsearch;\n\n// Using Kernel Builder.\nvar kernelBuilder = Kernel\n    .CreateBuilder()\n    .AddElasticsearchVectorStore(new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\")));\n```\n\n```csharp\nusing Microsoft.SemanticKernel;\nusing Elastic.Clients.Elasticsearch;\n\n// Using IServiceCollection with ASP.NET Core.\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.Services.AddElasticsearchVectorStore(new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\")));\n```\n\nExtension methods that take no parameters are also provided. These require an instance of the `Elastic.Clients.Elasticsearch.ElasticsearchClient` class to be separately registered with the dependency injection container.\n\n```csharp\nusing Microsoft.Extensions.DependencyInjection;\nusing Microsoft.SemanticKernel;\nusing Elastic.Clients.Elasticsearch;\n\n// Using Kernel Builder.\nvar kernelBuilder = Kernel.CreateBuilder();\nkernelBuilder.Services.AddSingleton\u003cElasticsearchClient\u003e(sp =\u003e\n    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\"))));\nkernelBuilder.AddElasticsearchVectorStore();\n```\n\n```csharp\nusing Microsoft.Extensions.DependencyInjection;\nusing Microsoft.SemanticKernel;\nusing Elastic.Clients.Elasticsearch;\n\n// Using IServiceCollection with ASP.NET Core.\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.Services.AddSingleton\u003cElasticsearchClient\u003e(sp =\u003e\n    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\"))));\nbuilder.Services.AddElasticsearchVectorStore();\n```\n\nYou can construct an Elasticsearch Vector Store instance directly.\n\n```csharp\nusing Elastic.SemanticKernel.Connectors.Elasticsearch;\nusing Elastic.Clients.Elasticsearch;\n\nvar vectorStore = new ElasticsearchVectorStore(\n    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\"))));\n```\n\nIt is possible to construct a direct reference to a named collection.\n\n```csharp\nusing Elastic.SemanticKernel.Connectors.Elasticsearch;\nusing Elastic.Clients.Elasticsearch;\n\nvar collection = new ElasticsearchVectorStoreRecordCollection\u003cHotel\u003e(\n    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\"))),\n    \"skhotels\");\n```\n\n## Data mapping\n\nThe Elasticsearch connector will use `System.Text.Json.JsonSerializer` to do mapping.\nSince Elasticsearch stores documents with a separate key/id and value, the mapper will serialize all properties except for the key to a JSON object\nand use that as the value.\n\nUsage of the `JsonPropertyNameAttribute` is supported if a different storage name to the\ndata model property name is required. It is also possible to use a custom `JsonSerializerOptions` instance with a customized property naming policy. To enable this, \na custom source serializer must be configured.\n\n```csharp\nusing Elastic.SemanticKernel.Connectors.Elasticsearch;\nusing Elastic.Clients.Elasticsearch;\nusing Elastic.Clients.Elasticsearch.Serialization;\nusing Elastic.Transport;\n\nvar nodePool = new SingleNodePool(new Uri(\"http://localhost:9200\"));\nvar settings = new ElasticsearchClientSettings(\n    nodePool,\n    sourceSerializer: (defaultSerializer, settings) =\u003e\n        new DefaultSourceSerializer(settings, options =\u003e \n            options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper));\nvar client = new ElasticsearchClient(settings);\n\nvar collection = new ElasticsearchVectorStoreRecordCollection\u003cHotel\u003e(\n    client,\n    \"skhotelsjson\");\n```\n\nAs an alternative, the `DefaultFieldNameInferrer` lambda function can be configured to achieve the same result or to even further customize property naming based on dynamic conditions.\n\n```csharp\nusing Elastic.SemanticKernel.Connectors.Elasticsearch;\nusing Elastic.Clients.Elasticsearch;\n\nvar settings = new ElasticsearchClientSettings(new Uri(\"http://localhost:9200\"));\nsettings.DefaultFieldNameInferrer(name =\u003e JsonNamingPolicy.SnakeCaseUpper.ConvertName(name));\nvar client = new ElasticsearchClient(settings);\n\nvar collection = new ElasticsearchVectorStoreRecordCollection\u003cHotel\u003e(\n    client,\n    \"skhotelsjson\");\n```\n\nSince a naming policy of snake case upper was chosen, here is an example of how this data type will be set in Elasticsearch.\nAlso note the use of `JsonPropertyNameAttribute` on the `Description` property to further customize the storage naming.\n\n```csharp\nusing System.Text.Json.Serialization;\nusing Microsoft.Extensions.VectorData;\n\npublic class Hotel\n{\n    [VectorStoreRecordKey]\n    public string HotelId { get; set; }\n\n    [VectorStoreRecordData(IsFilterable = true)]\n    public string HotelName { get; set; }\n\n    [JsonPropertyName(\"HOTEL_DESCRIPTION\")]\n    [VectorStoreRecordData(IsFullTextSearchable = true)]\n    public string Description { get; set; }\n\n    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw)]\n    public ReadOnlyMemory\u003cfloat\u003e? DescriptionEmbedding { get; set; }\n}\n```\n\n```json\n{\n  \"_index\" : \"skhotelsjson\",\n  \"_id\" : \"h1\",\n  \"_source\" : {\n    \"HOTEL_NAME\" : \"Hotel Happy\",\n    \"HOTEL_DESCRIPTION\" : \"A place where everyone can be happy.\",\n    \"DESCRIPTION_EMBEDDING\" : [\n      0.9,\n      0.1,\n      0.1,\n      0.1\n    ]\n  }\n}\n```\n\n## License\n\nElasticsearch connector for Microsoft Semantic Kernel is licensed under the Apache 2.0 license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fsemantic-kernel-net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felastic%2Fsemantic-kernel-net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fsemantic-kernel-net/lists"}