Registry / search / azure-ai-search-orm

azure-ai-search-orm

library0.0.20jsnpmunverified

A fully type-safe ORM for Azure AI Search (formerly Cognitive Search), version 0.0.20. It provides a fluent schema definition API inspired by Drizzle ORM, with strong TypeScript support for field types, filters, sorters, facets, suggesters, and automatic field mappings. The package wraps the official @azure/search-documents client and supports ESM/CommonJS. It's ideal for developers who want type safety and a declarative schema rather than raw REST API calls. Release cadence is monthly, with features closely tracking Azure AI Search updates. Differentiators: schema-based mapping, automatic indexer field mappings, and a clean DSL for complex types.

search database

npm install azure-ai-search-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AZURE-AI-SEARCH-OR

azure-ai-search-orm

searchjavascriptv0.0.20

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

index

✓ import { index } from 'azure-ai-search-orm'

✗ const { index } = require('azure-ai-search-orm')

ESM-only import; CommonJS require() will fail. Use ES modules.

string

✓ import { string } from 'azure-ai-search-orm'

✗ import { String } from 'azure-ai-search-orm'

Case-sensitive: lowercase 'string' not 'String'.

connect

✓ import { connect } from 'azure-ai-search-orm'

Valid both as named import (ESM) or const { connect } = require(...) with dynamic import; but ESM is preferred.

SearchIndexClient

✓ import { SearchIndexClient } from '@azure/search-documents'

✗ import { SearchIndexClient } from 'azure-ai-search-orm'

SearchIndexClient belongs to @azure/search-documents, not this package. Package exports only ORM functions.

Shows how to define an index schema, connect to Azure AI Search, and perform a basic search with select fields.

import { SearchIndexClient } from '@azure/search-documents'; import { DefaultAzureCredential } from '@azure/identity'; import { index, string, int32, connect } from 'azure-ai-search-orm'; // Define schema const realEstate = index('realestate-us-sample-index', { listingId: string('listingId').key(), beds: int32('beds').filterable().sortable().facetable(), baths: int32('baths').filterable().sortable().facetable(), description: string('description').searchable(), squareFeet: int32('sqft').filterable().sortable().facetable(), }); // Create client const endpoint = process.env.SEARCH_ENDPOINT ?? ''; const credential = new DefaultAzureCredential(); const searchIndexClient = new SearchIndexClient(endpoint, credential); // Connect and search const srch = connect(searchIndexClient, realEstate); const data = await srch.search(undefined, { top: 20, select: ['listingId', 'description'], }); console.log(data);

Debug

Known issues

gotchaField names in the ORM do not match datasource column names; automatic field mapping only works for top-level primitives. Complex fields require exact match.

fix

Ensure complex type structures match the index definition exactly; field mapping is not supported for nested fields.

affects: >=0.0.1

deprecatedThe package name references 'Cognitive Search' but Azure service is now 'AI Search'. No breaking changes expected, but migration may occur.

fix

Continue using current APIs; watch for future versions that may align naming.

affects: >=0.0.20

gotchaThe default suggester name is 'sg'. If you define multiple suggesters, you must use a non-default name.

fix

Specify custom suggester name when calling suggest() if not using default.

affects: >=0.0.1

breakingv0.0.20 switched to ESM-only exports. CommonJS require() will fail.

fix

Use ES module imports (import { ... } from 'azure-ai-search-orm'). For CommonJS, use dynamic import: const module = await import('azure-ai-search-orm');

affects: >=0.0.20

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'search')

Missing or incorrect schema passed to connect()

fix

Ensure connect() receives a valid index schema (returned from index()) and a SearchIndexClient instance.

Could not find module: 'azure-ai-search-orm'

Package not installed or incorrect import path

fix

Run 'npm install azure-ai-search-orm' and verify import path is correct.

Field 'xyz' not found in schema

Referenced field name does not exist in schema definition

fix

Check schema field definitions and ensure the field name matches exactly (case-sensitive).

Upgrade

Version history

0.0.20latest on npm

Audit

Dependencies

@azure/search-documentsrequiredCore dependency providing SearchIndexClient and related classes

@azure/identityoptionalRequired for authentication via DefaultAzureCredential or other identity mechanisms

Agent activity

50 hits · last 30 days

node

Resources

githubhttps://github.com/ihusemann/ai-search-orm ↗

packageazure-ai-search-orm ↗

homepagehttps://github.com/ihusemann/ai-search-orm#readme ↗