Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(search): converge OpenSearch mappings so tagged calls are searchable (#5396)

gbirmanae66ba5f7f3a
diff --git a/infra/stacks/opensearch/helpers/README.md b/infra/stacks/opensearch/helpers/README.md
index e5a8af890b..c6ab7e3782 100644
--- a/infra/stacks/opensearch/helpers/README.md
+++ b/infra/stacks/opensearch/helpers/README.md
@@ -35,12 +35,36 @@ that can be swapped without a code deploy.
| Script | Purpose |
| ---------------------------- | ---------------------------------------------------------------------- |
| `verify_aliases.ts` | Pre/post-flight check: alias exists and points at the expected index. |
+| `verify_mappings.ts` | Pre/post-flight check: live mappings carry every field the code declares. |
| `add_alias.ts` | Idempotent additive alias (no reindex). |
| `reindex_with_alias_swap.ts` | Reindex + atomic swap (handles `remove_index` for bare physical case). |
-| `create_indices.ts` | Idempotent first-time creation of every versioned index + alias. |
+| `create_indices.ts` | Creates every versioned index + alias, and converges existing mappings. |
All migration scripts default to `DRY_RUN=true`; pass `DRY_RUN=false` to apply.
+## Adding a field to an existing index
+
+The index bodies in `create_indices.ts` are the source of truth for mappings.
+Every body is `dynamic: 'false'`, so a field the service writes but the live
+mapping lacks is dropped silently — and a search over it matches nothing
+rather than erroring. That is how `call_records_v2` shipped without
+`properties`/`name` and left tag filters on calls returning empty (macro-2731).
+
+So the flow for a new field is:
+
+1. Add it to the body in `create_indices.ts`.
+2. Run `bun scripts/create_indices.ts` (dry-run) against each environment and
+ read the plan, then `DRY_RUN=false` to apply. Existing indices keep their
+ data and gain only the fields they're missing, via `_mapping` PUT.
+3. Backfill the affected entity through `search_processing_service`
+ (`POST /internal/backfill/<entity>`) so documents indexed before the
+ mapping existed pick the field up.
+4. Confirm with `bun scripts/verify_mappings.ts`.
+
+Convergence is additive only. A field whose live `type` disagrees with the
+body is reported, never rewritten — changing a live field's type needs the
+reindex runbook below.
+
## Runbook: reindex with new mapping (zero downtime)
Use when you need to change a mapping that requires a full reindex (e.g.
diff --git a/infra/stacks/opensearch/helpers/package.json b/infra/stacks/opensearch/helpers/package.json
index 86180d07f4..c7cb6de157 100644
--- a/infra/stacks/opensearch/helpers/package.json
+++ b/infra/stacks/opensearch/helpers/package.json
@@ -12,6 +12,7 @@
"add_alias": "bun run scripts/add_alias.ts",
"reindex_with_alias_swap": "bun run scripts/reindex_with_alias_swap.ts",
"verify_aliases": "bun run scripts/verify_aliases.ts",
+ "verify_mappings": "bun run scripts/verify_mappings.ts",
"set_refresh_interval": "bun run set_refresh_interval.ts"
},
"author": "Will Hutchinson",
diff --git a/infra/stacks/opensearch/helpers/scripts/add_properties_field.ts b/infra/stacks/opensearch/helpers/scripts/add_properties_field.ts
deleted file mode 100644
index 6d6717ba01..0000000000
--- a/infra/stacks/opensearch/helpers/scripts/add_properties_field.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-require('dotenv').config();
-
-import { client } from '../client';
-import {
- CALL_RECORDS_ALIAS,
- CHATS_ALIAS,
- EMAILS_ALIAS,
- IS_DRY_RUN,
-} from '../constants';
-
-// Indexes that receive the nested entity-properties field additively
-// (documents shipped with it; projects_v1 was created with it).
-const SUPPORTED_INDEXES = [EMAILS_ALIAS, CHATS_ALIAS, CALL_RECORDS_ALIAS];
-
-async function addPropertiesField(dryRun: boolean) {
- const index = process.env.INDEX;
- if (!index || !SUPPORTED_INDEXES.includes(index)) {
- console.log(
- `⚠️ Set INDEX to one of: ${SUPPORTED_INDEXES.join(', ')}. Aborting.`
- );
- return;
- }
-
- const opensearchClient = client();
-
- console.log('\n' + '='.repeat(60));
- console.log(
- `Add nested properties field to "${index}" index ${dryRun ? '(DRY-RUN MODE)' : '(LIVE MODE)'}`
- );
- console.log('='.repeat(60));
-
- if (dryRun) {
- console.log('\n⚠️ DRY-RUN MODE: No changes will be made');
- }
-
- const indexExists = (await opensearchClient.indices.exists({ index })).body;
-
- if (!indexExists) {
- console.log(`⚠️ Index "${index}" does not exist. Aborting.`);
- return;
- }
-
- console.log('\nAdding nested properties field mapping...');
- const fields: Record<string, unknown> = {
- // Entity properties (e.g. tags), same nested shape as the documents
- // index so the shared property/tag filters apply unchanged. Emails:
- // thread-level values denormalized onto every message doc. Chats and
- // calls: values live on the parent doc only.
- properties: {
- type: 'nested' as const,
- properties: {
- definition_id: { type: 'keyword' as const },
- values: { type: 'keyword' as const },
- number_value: { type: 'double' as const },
- date_value: { type: 'date' as const },
- },
- },
- };
- // Calls also gain a searchable `name` field (custom name, falling back to
- // the channel name). Existing indexes only got channel_name; the calls
- // backfill re-populates `name` on every parent doc.
- if (index === CALL_RECORDS_ALIAS) {
- fields.name = {
- type: 'text' as const,
- fields: { keyword: { type: 'keyword' as const, ignore_above: 128 } },
- };
- }
- const mappingUpdate = { properties: fields };
-
- if (dryRun) {
- console.log('[DRY-RUN] Would add nested properties field mapping');
- } else {
- const putMappingResponse = await opensearchClient.indices.putMapping({
- index,
- body: mappingUpdate,
- });
-
- if (!putMappingResponse.body.acknowledged) {
- throw new Error('Failed to add field mapping');
- }
- console.log('✓ nested properties field mapping added');
- }
-
- console.log('\n' + '='.repeat(60));
- console.log('Done!');
- console.log('='.repeat(60));
-
- if (dryRun) {
- console.log('\nTo run for real, set DRY_RUN=false environment variable\n');
- } else {
- console.log(
- `\n✓ properties field has been added to the "${index}" index mapping.`
- );
- console.log(
- '✓ To backfill existing tags, POST /internal/backfill/properties with the matching entity_type.\n'
- );
- }
-}
-
-addPropertiesField(IS_DRY_RUN);
diff --git a/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts b/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts
index df300e1822..788788045e 100644
--- a/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts
+++ b/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts
@@ -1,5 +1,10 @@
import { describe, expect, test } from 'bun:test';
-import { planCreateIndex } from './create_indices';
+import {
+ INDEX_SPECS,
+ planCreateIndex,
+ planMappingConvergence,
+ selectIndexSpecs,
+} from './create_indices';
describe('planCreateIndex', () => {
test('fresh env — index missing, alias free → create with alias', () => {
@@ -78,3 +83,147 @@ describe('planCreateIndex', () => {
expect(plan.kind).toBe('defer_alias');
});
});
+
+describe('planMappingConvergence', () => {
+ const TAG_PROPERTIES = {
+ type: 'nested',
+ properties: {
+ definition_id: { type: 'keyword' },
+ values: { type: 'keyword' },
+ },
+ };
+
+ test('live mapping matches the body → nothing to do', () => {
+ const plan = planMappingConvergence({
+ desired: { entity_id: { type: 'keyword' }, properties: TAG_PROPERTIES },
+ live: { entity_id: { type: 'keyword' }, properties: TAG_PROPERTIES },
+ });
+ expect(plan.missingPaths).toEqual([]);
+ expect(plan.conflictPaths).toEqual([]);
+ expect(plan.updates).toEqual({});
+ });
+
+ test('macro-2731: index predates the nested properties + name fields → add both', () => {
+ const plan = planMappingConvergence({
+ desired: {
+ entity_id: { type: 'keyword' },
+ name: {
+ type: 'text',
+ fields: { keyword: { type: 'keyword', ignore_above: 128 } },
+ },
+ properties: TAG_PROPERTIES,
+ },
+ live: { entity_id: { type: 'keyword' } },
+ });
+ expect(plan.missingPaths).toEqual(['name', 'properties']);
+ expect(plan.conflictPaths).toEqual([]);
+ expect(Object.keys(plan.updates)).toEqual(['name', 'properties']);
+ expect(plan.updates.properties).toEqual(TAG_PROPERTIES);
+ });
+
+ test('a new member of an existing nested field is additive', () => {
+ const plan = planMappingConvergence({
+ desired: {
+ properties: {
+ type: 'nested',
+ properties: {
+ definition_id: { type: 'keyword' },
+ values: { type: 'keyword' },
+ date_value: { type: 'date' },
+ },
+ },
+ },
+ live: { properties: TAG_PROPERTIES },
+ });
+ expect(plan.missingPaths).toEqual(['properties.date_value']);
+ expect(Object.keys(plan.updates)).toEqual(['properties']);
+ });
+
+ test('a new multi-field under an existing field is additive', () => {
+ const plan = planMappingConvergence({
+ desired: {
+ channel_name: {
+ type: 'text',
+ fields: { keyword: { type: 'keyword', ignore_above: 128 } },
+ },
+ },
+ live: { channel_name: { type: 'text' } },
+ });
+ expect(plan.missingPaths).toEqual(['channel_name.keyword']);
+ expect(Object.keys(plan.updates)).toEqual(['channel_name']);
+ });
+
+ test('parameter-only differences are ignored so runs stay quiet', () => {
+ const plan = planMappingConvergence({
+ // OpenSearch echoes a normalized mapping: defaults like `index: true`
+ // and `doc_values: true` come back omitted.
+ desired: {
+ channel_id: { type: 'keyword', index: true, doc_values: true },
+ },
+ live: { channel_id: { type: 'keyword' } },
+ });
+ expect(plan.missingPaths).toEqual([]);
+ expect(plan.updates).toEqual({});
+ });
+
+ test('a changed type is reported, never applied', () => {
+ const plan = planMappingConvergence({
+ desired: { started_at_millis: { type: 'date', format: 'epoch_millis' } },
+ live: { started_at_millis: { type: 'long' } },
+ });
+ expect(plan.conflictPaths).toEqual(['started_at_millis']);
+ expect(plan.updates).toEqual({});
+ });
+
+ test('a conflict keeps its whole top-level field out of the update', () => {
+ const plan = planMappingConvergence({
+ desired: {
+ properties: {
+ type: 'nested',
+ properties: {
+ values: { type: 'keyword' },
+ number_value: { type: 'double' },
+ },
+ },
+ },
+ live: {
+ properties: {
+ type: 'nested',
+ properties: { values: { type: 'text' } },
+ },
+ },
+ });
+ expect(plan.missingPaths).toEqual(['properties.number_value']);
+ expect(plan.conflictPaths).toEqual(['properties.values']);
+ expect(plan.updates).toEqual({});
+ });
+
+ test('an index with no live mapping yet takes every field', () => {
+ const plan = planMappingConvergence({
+ desired: { entity_id: { type: 'keyword' } },
+ live: undefined,
+ });
+ expect(plan.missingPaths).toEqual(['entity_id']);
+ expect(Object.keys(plan.updates)).toEqual(['entity_id']);
+ });
+});
+
+describe('selectIndexSpecs', () => {
+ test('no filter runs every index', () => {
+ expect(selectIndexSpecs(INDEX_SPECS, undefined)).toEqual(INDEX_SPECS);
+ });
+
+ test('filters by alias', () => {
+ const selected = selectIndexSpecs(INDEX_SPECS, 'call_records');
+ expect(selected.map((s) => s.indexName)).toEqual(['call_records_v2']);
+ });
+
+ test('filters by physical index name', () => {
+ const selected = selectIndexSpecs(INDEX_SPECS, 'call_records_v2');
+ expect(selected.map((s) => s.aliasName)).toEqual(['call_records']);
+ });
+
+ test('an unknown filter selects nothing so the caller can abort', () => {
+ expect(selectIndexSpecs(INDEX_SPECS, 'nope')).toEqual([]);
+ });
+});
diff --git a/infra/stacks/opensearch/helpers/scripts/create_indices.ts b/infra/stacks/opensearch/helpers/scripts/create_indices.ts
index 30bb304f70..a588fd7932 100644
--- a/infra/stacks/opensearch/helpers/scripts/create_indices.ts
+++ b/infra/stacks/opensearch/helpers/scripts/create_indices.ts
@@ -18,7 +18,7 @@ import {
SLOWLOG_SETTINGS,
} from '../constants';
-type CreateIndexArgs = {
+export type CreateIndexArgs = {
indexName: string;
aliasName: string;
body: Record<string, unknown>;
@@ -95,6 +95,196 @@ export function planCreateIndex(state: CreateIndexState): CreatePlan {
return { kind: 'create_with_alias' };
}
+/**
+ * Field-level drift between an index body in this file and the mapping that is
+ * actually live on the cluster.
+ *
+ * `updates` is the `properties` payload of a `_mapping` PUT: the full desired
+ * definition of every top-level field that is missing fields, which OpenSearch
+ * merges additively. `missingPaths` and `conflictPaths` are dotted field paths
+ * for the operator log.
+ */
+export type MappingConvergencePlan = {
+ updates: Record<string, unknown>;
+ missingPaths: string[];
+ conflictPaths: string[];
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+ typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const fieldType = (definition: unknown): string | undefined => {
+ if (!isRecord(definition)) return undefined;
+ return typeof definition.type === 'string' ? definition.type : undefined;
+};
+
+/**
+ * Sub-fields of one field definition: object/nested members under
+ * `properties`, plus multi-fields under `fields`. A field can never have both,
+ * so flattening them into one namespace can't collide.
+ */
+const subFields = (definition: unknown): Record<string, unknown> => {
+ if (!isRecord(definition)) return {};
+ return {
+ ...(isRecord(definition.properties) ? definition.properties : {}),
+ ...(isRecord(definition.fields) ? definition.fields : {}),
+ };
+};
+
+function collectFieldDrift(
+ path: string,
+ desired: unknown,
+ live: unknown,
+ missingPaths: string[],
+ conflictPaths: string[]
+) {
+ const desiredType = fieldType(desired);
+ const liveType = fieldType(live);
+ // A type change can't be applied additively — it needs a reindex, so record
+ // it and stop descending (children of a differently-typed field are moot).
+ if (desiredType && liveType && desiredType !== liveType) {
+ conflictPaths.push(path);
+ return;
+ }
+
+ const desiredSubFields = subFields(desired);
+ const liveSubFields = subFields(live);
+ for (const [name, desiredSubField] of Object.entries(desiredSubFields)) {
+ const subPath = `${path}.${name}`;
+ if (!(name in liveSubFields)) {
+ missingPaths.push(subPath);
+ continue;
+ }
+ collectFieldDrift(
+ subPath,
+ desiredSubField,
+ liveSubFields[name],
+ missingPaths,
+ conflictPaths
+ );
+ }
+}
+
+/**
+ * Pure decision: which fields does the live mapping lack, and which of them
+ * can be added without a reindex?
+ *
+ * Only field *presence* is compared, never per-field parameters: OpenSearch
+ * echoes back a normalized mapping (defaults omitted, some values rewritten),
+ * so diffing parameters would report drift on every index forever. A field
+ * whose `type` disagrees lands in `conflictPaths` and is left alone — changing
+ * a live field's type requires `reindex_with_alias_swap.ts`. Anything else
+ * missing is additive, so the whole top-level definition goes into `updates`
+ * for OpenSearch to merge.
+ */
+export function planMappingConvergence(args: {
+ desired: Record<string, unknown> | undefined;
+ live: Record<string, unknown> | undefined;
+}): MappingConvergencePlan {
+ const desired = args.desired ?? {};
+ const live = args.live ?? {};
+
+ const updates: Record<string, unknown> = {};
+ const missingPaths: string[] = [];
+ const conflictPaths: string[] = [];
+
+ for (const [name, desiredDefinition] of Object.entries(desired)) {
+ if (!(name in live)) {
+ missingPaths.push(name);
+ updates[name] = desiredDefinition;
+ continue;
+ }
+
+ const fieldMissing: string[] = [];
+ const fieldConflicts: string[] = [];
+ collectFieldDrift(
+ name,
+ desiredDefinition,
+ live[name],
+ fieldMissing,
+ fieldConflicts
+ );
+ missingPaths.push(...fieldMissing);
+ conflictPaths.push(...fieldConflicts);
+ // Sending a definition that carries a conflict would be rejected wholesale,
+ // taking the additive sub-fields down with it.
+ if (fieldMissing.length > 0 && fieldConflicts.length === 0) {
+ updates[name] = desiredDefinition;
+ }
+ }
+
+ return { updates, missingPaths, conflictPaths };
+}
+
+/**
+ * Bring an existing index's mapping up to the body declared above by adding
+ * whatever fields it is missing.
+ *
+ * Index creation is one-shot, so a field added to a body here never reaches an
+ * index that already exists — and because every body is `dynamic: 'false'`,
+ * writes of the new field are dropped silently and searches over it match
+ * nothing (macro-2731: `call_records_v2` never got `properties`/`name`, so tag
+ * filters and name matches on calls returned empty). Converging on every run
+ * makes the body the single source of truth instead of a one-off script.
+ */
+async function convergeMapping(
+ opensearchClient: Client,
+ indexName: string,
+ body: Record<string, unknown>
+) {
+ const desiredMappings = isRecord(body.mappings) ? body.mappings : undefined;
+ const desired = isRecord(desiredMappings?.properties)
+ ? (desiredMappings?.properties as Record<string, unknown>)
+ : undefined;
+
+ const response = await opensearchClient.indices.getMapping({
+ index: indexName,
+ });
+ const liveMappings = (response.body ?? {})[indexName]?.mappings;
+ const live = isRecord(liveMappings?.properties)
+ ? (liveMappings?.properties as Record<string, unknown>)
+ : undefined;
+
+ const plan = planMappingConvergence({ desired, live });
+
+ for (const path of plan.conflictPaths) {
+ console.log(
+ `${indexName}: ⚠️ "${path}" has a different type live than in this file. ` +
+ `A type change needs a reindex — run reindex_with_alias_swap.ts.`
+ );
+ }
+
+ if (Object.keys(plan.updates).length === 0) {
+ if (plan.conflictPaths.length === 0) {
+ console.log(`${indexName}: mapping matches this file`);
+ }
+ return;
+ }
+
+ console.log(
+ `${indexName}: mapping is missing ${plan.missingPaths.length} field(s): ${plan.missingPaths.join(', ')}`
+ );
+
+ if (IS_DRY_RUN) {
+ console.log(
+ `[DRY-RUN] Would add ${Object.keys(plan.updates).join(', ')} to ${indexName}`
+ );
+ return;
+ }
+
+ const putMappingResponse = await opensearchClient.indices.putMapping({
+ index: indexName,
+ body: { properties: plan.updates },
+ });
+ if (!putMappingResponse.body.acknowledged) {
+ throw new Error(`Failed to add mapping fields to ${indexName}`);
+ }
+ console.log(
+ `✓ ${indexName}: added ${Object.keys(plan.updates).join(', ')}. ` +
+ `Backfill the affected entity to populate existing docs.`
+ );
+}
+
async function createIndexWithAlias(
opensearchClient: Client,
{ indexName, aliasName, body }: CreateIndexArgs
@@ -142,17 +332,19 @@ async function createIndexWithAlias(
switch (plan.kind) {
case 'noop':
console.log(`${indexName}: ${plan.reason}`);
+ await convergeMapping(opensearchClient, indexName, body);
return;
case 'add_alias':
if (IS_DRY_RUN) {
console.log(`[DRY-RUN] Would add alias ${aliasName} -> ${indexName}`);
- return;
+ } else {
+ console.log(`Adding alias ${aliasName} -> ${indexName}`);
+ await opensearchClient.indices.putAlias({
+ index: indexName,
+ name: aliasName,
+ });
}
- console.log(`Adding alias ${aliasName} -> ${indexName}`);
- await opensearchClient.indices.putAlias({
- index: indexName,
- name: aliasName,
- });
+ await convergeMapping(opensearchClient, indexName, body);
return;
case 'create_with_alias':
if (IS_DRY_RUN) {
@@ -182,6 +374,7 @@ async function createIndexWithAlias(
return;
case 'defer_alias':
console.log(`${indexName}: ${plan.nextStep}`);
+ await convergeMapping(opensearchClient, indexName, body);
return;
}
}
@@ -718,46 +911,72 @@ const CALL_RECORDS_V2_BODY = {
},
};
+/**
+ * Every index this repo owns, with the mapping it is supposed to have.
+ * `verify_mappings.ts` reads the same list so a drift check and a converging
+ * run can never disagree about what the desired mapping is.
+ *
+ * chats and call_records use parent/child join mappings (bodies inlined above
+ * as CHATS_V2_BODY / CALL_RECORDS_V2_BODY).
+ */
+export const INDEX_SPECS: CreateIndexArgs[] = [
+ {
+ indexName: DOCUMENTS_INDEX,
+ aliasName: DOCUMENTS_ALIAS,
+ body: DOCUMENT_BODY,
+ },
+ { indexName: EMAILS_INDEX, aliasName: EMAILS_ALIAS, body: EMAIL_BODY },
+ { indexName: CHANNELS_INDEX, aliasName: CHANNELS_ALIAS, body: CHANNEL_BODY },
+ { indexName: CHATS_INDEX, aliasName: CHATS_ALIAS, body: CHATS_V2_BODY },
+ {
+ indexName: CALL_RECORDS_INDEX,
+ aliasName: CALL_RECORDS_ALIAS,
+ body: CALL_RECORDS_V2_BODY,
+ },
+ { indexName: PROJECTS_INDEX, aliasName: PROJECTS_ALIAS, body: PROJECTS_BODY },
+];
+
+/**
+ * Narrow a run to one index by alias or physical name (`INDEX=call_records`).
+ *
+ * An environment can sit mid-migration on one index while another needs a
+ * field added — prod held `emails` on `emails_v1` while `call_records_v2` was
+ * missing its `properties` mapping, and an unscoped run there would have
+ * created an empty `emails_v2` as a side effect. Scoping keeps a mapping fix
+ * from touching an unrelated migration.
+ */
+export function selectIndexSpecs(
+ specs: CreateIndexArgs[],
+ filter: string | undefined
+): CreateIndexArgs[] {
+ if (!filter) return specs;
+ return specs.filter(
+ (spec) => spec.indexName === filter || spec.aliasName === filter
+ );
+}
+
async function createIndices() {
const opensearchClient = client();
+ const filter = process.env.INDEX;
+ const specs = selectIndexSpecs(INDEX_SPECS, filter);
+ if (specs.length === 0) {
+ console.log(
+ `⚠️ INDEX="${filter}" matches no index. Known: ` +
+ `${INDEX_SPECS.map((s) => s.aliasName).join(', ')}. Aborting.`
+ );
+ return;
+ }
+
console.log(
- `Creating indices... ${IS_DRY_RUN ? '(DRY-RUN MODE — set DRY_RUN=false to apply)' : '(LIVE MODE)'}`
+ `Creating indices and converging mappings${filter ? ` for "${filter}"` : ''}... ${IS_DRY_RUN ? '(DRY-RUN MODE — set DRY_RUN=false to apply)' : '(LIVE MODE)'}`
);
try {
- await createIndexWithAlias(opensearchClient, {
- indexName: DOCUMENTS_INDEX,
- aliasName: DOCUMENTS_ALIAS,
- body: DOCUMENT_BODY,
- });
- await createIndexWithAlias(opensearchClient, {
- indexName: EMAILS_INDEX,
- aliasName: EMAILS_ALIAS,
- body: EMAIL_BODY,
- });
- await createIndexWithAlias(opensearchClient, {
- indexName: CHANNELS_INDEX,
- aliasName: CHANNELS_ALIAS,
- body: CHANNEL_BODY,
- });
- // chats and call_records use parent/child join mappings (bodies inlined
- // above as CHATS_V2_BODY / CALL_RECORDS_V2_BODY). Idempotent — no-ops where
- // they already exist.
- await createIndexWithAlias(opensearchClient, {
- indexName: CHATS_INDEX,
- aliasName: CHATS_ALIAS,
- body: CHATS_V2_BODY,
- });
- await createIndexWithAlias(opensearchClient, {
- indexName: CALL_RECORDS_INDEX,
- aliasName: CALL_RECORDS_ALIAS,
- body: CALL_RECORDS_V2_BODY,
- });
- await createIndexWithAlias(opensearchClient, {
- indexName: PROJECTS_INDEX,
- aliasName: PROJECTS_ALIAS,
- body: PROJECTS_BODY,
- });
+ // Idempotent — indices that already exist keep their data and only gain
+ // fields this file declares that they are missing.
+ for (const spec of specs) {
+ await createIndexWithAlias(opensearchClient, spec);
+ }
console.log('done');
} catch (error) {
console.error('Error', error);
diff --git a/infra/stacks/opensearch/helpers/scripts/verify_mappings.ts b/infra/stacks/opensearch/helpers/scripts/verify_mappings.ts
new file mode 100644
index 0000000000..da9d7aa47e
--- /dev/null
+++ b/infra/stacks/opensearch/helpers/scripts/verify_mappings.ts
@@ -0,0 +1,113 @@
+/**
+ * Pre/post-flight check: compare every live index mapping against the body
+ * declared for it in create_indices.ts. Exits non-zero when an index is
+ * missing fields the code expects, or when a field's type disagrees.
+ *
+ * Every index body is `dynamic: 'false'`, so a field that exists in code but
+ * not on the cluster fails silently: the service writes it, OpenSearch drops
+ * it, and searches over it match nothing. Run this after deploying code that
+ * indexes a new field, and after `create_indices.ts` to confirm convergence.
+ *
+ * Usage:
+ * bun scripts/verify_mappings.ts
+ * INDEX=call_records bun scripts/verify_mappings.ts # one index only
+ */
+import type { Client } from '@opensearch-project/opensearch';
+import {
+ INDEX_SPECS,
+ type MappingConvergencePlan,
+ planMappingConvergence,
+ selectIndexSpecs,
+} from './create_indices';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+ typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const mappingProperties = (
+ mappings: unknown
+): Record<string, unknown> | undefined => {
+ if (!isRecord(mappings)) return undefined;
+ return isRecord(mappings.properties) ? mappings.properties : undefined;
+};
+
+async function livePropertiesFor(
+ opensearchClient: Client,
+ indexName: string
+): Promise<Record<string, unknown> | undefined> {
+ const response = await opensearchClient.indices.getMapping({
+ index: indexName,
+ });
+ return mappingProperties((response.body ?? {})[indexName]?.mappings);
+}
+
+function describe(indexName: string, plan: MappingConvergencePlan): boolean {
+ const drifted = plan.missingPaths.length > 0 || plan.conflictPaths.length > 0;
+ const status = drifted ? 'FAIL' : 'OK';
+ console.log(`${indexName.padEnd(20)} [${status}]`);
+ if (plan.missingPaths.length > 0) {
+ console.log(` missing: ${plan.missingPaths.join(', ')}`);
+ console.log(
+ ` fix: DRY_RUN=false bun scripts/create_indices.ts, then backfill the entity`
+ );
+ }
+ for (const path of plan.conflictPaths) {
+ console.log(
+ ` type conflict: "${path}" — needs reindex_with_alias_swap.ts`
+ );
+ }
+ return !drifted;
+}
+
+async function main() {
+ await import('dotenv').then((m) => m.config());
+ const { client } = await import('../client');
+
+ const opensearchClient = client();
+ const filter = process.env.INDEX;
+ const specs = selectIndexSpecs(INDEX_SPECS, filter);
+ if (specs.length === 0) {
+ console.error(
+ `INDEX="${filter}" matches no index. Known: ` +
+ `${INDEX_SPECS.map((s) => s.aliasName).join(', ')}.`
+ );
+ process.exit(1);
+ }
+
+ let allOk = true;
+ console.log('index [status]');
+ console.log('-'.repeat(70));
+
+ for (const { indexName, body } of specs) {
+ const exists = (await opensearchClient.indices.exists({ index: indexName }))
+ .body;
+ if (!exists) {
+ console.log(`${indexName.padEnd(20)} [FAIL]`);
+ console.log(
+ ` missing index — run DRY_RUN=false bun scripts/create_indices.ts`
+ );
+ allOk = false;
+ continue;
+ }
+
+ const plan = planMappingConvergence({
+ desired: mappingProperties(body.mappings),
+ live: await livePropertiesFor(opensearchClient, indexName),
+ });
+ if (!describe(indexName, plan)) {
+ allOk = false;
+ }
+ }
+
+ if (!allOk) {
+ console.error('\nMapping verification failed.');
+ process.exit(1);
+ }
+ console.log('\nEvery index mapping matches create_indices.ts.');
+}
+
+if (import.meta.main) {
+ main().catch((err) => {
+ console.error('Error', err);
+ process.exit(1);
+ });
+}