> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-metadata.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Breaking Changes - Applications & Automation | Official Documentation

> Search Indexing app config removals, RDF Index app defaults, Data Insights module config, MCP tool contracts and CSV background jobs in OpenMetadata 2.0.

# Applications & Automation

Four installed applications have their stored configuration rewritten by the 2.0.0 migration. If you
manage application configuration as code, read this before you replay it.

## Search Indexing app configuration fields removed

<Warning>
  **Breaking.** Affects scripted reindex triggers and infrastructure-as-code.
</Warning>

```diff theme={null}
- "recreateIndex": { "type": "boolean", "default": true },
- "useDistributedIndexing": { "type": "boolean", "default": true },
```

In 2.0 **reindex always recreates the index** and distributed indexing is always used.

Supporting infrastructure added by the migration:

| Table                      | Purpose                                                        |
| -------------------------- | -------------------------------------------------------------- |
| `search_index_job`         | Distributed reindex job tracking                               |
| `search_index_retry_queue` | Retry queue for failed search-index writes, with claim leasing |

<Warning>
  Any automation that triggers a reindex with `{"recreateIndex": false}` — for example an "incremental
  reindex" job — must drop the field. There is no incremental mode in 2.0.
</Warning>

New diagnostics ship alongside: reindex-drift and index-health checks in `/v1/system/validate`, plus a
cluster-fitness diagnostic.

## RDF Index app defaults changed

<Warning>
  **Behavioural — the migration overwrites your settings.**
</Warning>

| Setting                          | Before            | After                               |
| -------------------------------- | ----------------- | ----------------------------------- |
| `appSchedule.cronExpression`     | daily             | **`0 0 * * 6`** (weekly, Saturday)  |
| `appConfiguration.recreateIndex` | incremental       | **`true`** (full rebuild every run) |
| `appConfiguration.entities`      | operator's subset | **`["all"]`**                       |

Incremental RDF indexing produced unbounded triple growth because relationship-removal paths were not
fully reconciled. With a per-run clear the dataset always converges to the relational state, and a
weekly cadence keeps per-run cost from saturating the triple store.

The `entities` reset is a safety measure — with a full rebuild issuing a clear before indexing, a
narrowed entity subset would wipe triples for entity types still present in the database.

<Warning>
  Your `entities` subset is not preserved. Reapply it after the migration if you need partial RDF
  indexing, understanding that the following run will still clear first.
</Warning>

### RDF configuration defaults

| Field                             | 1.13       | 2.0         |
| --------------------------------- | ---------- | ----------- |
| `bulkEntityBatchSize`             | `50`       | `100`       |
| `bulkRelationshipSourceBatchSize` | `25`       | `100`       |
| `inferenceEnabled`                | **`true`** | **`false`** |
| `bulkLineageEdgeBatchSize`        | —          | `50` (new)  |

<Warning>
  RDF inference is now off. SPARQL queries relying on inferred triples return fewer results. Set
  `RDF_INFERENCE_ENABLED=true` to restore 1.13 behaviour.
</Warning>

## Data Insights app: the `dataQuality` module is removed

<Warning>
  **Breaking.** A stored configuration containing `moduleConfiguration.dataQuality` prevents
  `DataInsightsApplication` from deserialising at startup. See
  [Data Quality](/v2.0.x-SNAPSHOT/deployment/upgrade/breaking-changes/data-quality).
</Warning>

## MCP application configuration removed

<Warning>
  **Breaking.** Affects MCP deployments.
</Warning>

MCP configuration lives **solely** in the `mcpConfiguration` setting. The application-level copy —
which no code read — is dropped by the migration and the now-empty configure step is hidden in the UI.

<Tip>
  Configure MCP through **Settings → MCP**, not through the application's configuration.
</Tip>

## Runtime-only fields stripped from stored application data

<Note>
  **Behavioural and security-relevant.**
</Note>

`openMetadataServerConnection` and `privateConfiguration` were being persisted into application rows
and version history. They are runtime-only and are removed by the migration. Separately, 2.0 stops
exposing the application bot JWT and `privateConfiguration` secrets in API responses.

<Tip>
  If your tooling read the application bot token out of `/v1/apps/...`, obtain it through the bot API
  instead.
</Tip>

## Application configuration union changed

<Note>
  **Behavioural.** Affects generated models and strict validators.
</Note>

The `appConfig` union drops the three Collate AI agent configurations and gains a permissive terminal
branch. Branch **indexes shift**, so generated unions that key on position must be regenerated rather
than hand-patched.

## New tenant-wide application configuration setting

<Info>
  **Additive.**
</Info>

`settingType: "appConfiguration"` is backed by a new schema:

```json theme={null}
{ "defaultAppMode": "ai | classic | null" }
```

It is seeded from YAML or environment on first boot, then database-backed and admin-mutable at runtime
— YAML is ignored once a database row exists. Precedence is **user preference → persona app mode →
tenant default**. See
[UI, Personas & Customization](/v2.0.x-SNAPSHOT/deployment/upgrade/breaking-changes/ui-and-customization).

## MCP tool contracts

<Warning>
  **Breaking for MCP clients that parse responses.** No tools are removed, but **7 tools are added** and
  **15 change**.
</Warning>

### New tools

`create_context_memory`, `find_context`, `get_asset_context`, `get_company_context`,
`get_knowledge_content`, `get_persona_context` and `search_company_context` — all Context Center and
AI-context tools.

### Changed tools

`create_classification`, `create_data_product`, `create_domain`, `create_glossary`,
`create_glossary_term`, `create_lineage`, `create_metric`, `create_tag`, `create_test_case`,
`get_entity_lineage`, `get_test_definitions`, `patch_entity`, `root_cause_analysis`, `search_metadata`
and `semantic_search`.

### Contract changes that will break clients

| Change                                               | Detail                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`queryFilter` no longer honours `size` or `aggs`** | A `size` or `aggs` key inside `search_metadata`'s `queryFilter` is **ignored**. Read `totalFound` from the response for counts, or set `includeAggregations=true` for facets. Count queries written as `{"size": 0, "aggs": {...}}` silently return a normal result page in 2.0. |
| **Opaque `nextCursor` pagination**                   | All read tools page behind a single opaque cursor contract instead of per-tool offset conventions.                                                                                                                                                                               |
| **`structuredContent` and `isError`**                | Tools emit `structuredContent`, and soft errors are flagged via `isError` rather than returned as prose.                                                                                                                                                                         |
| **Response size budget**                             | A global budget trims wide payloads. Read tools stay under the cap **by paging items, not by truncating content**, so a response can now be a partial page where 1.13 returned a truncated blob.                                                                                 |
| **`queries` is not a retrievable field**             | `search_metadata`'s `fields` no longer resolves `queries`. Search `entityType='query'` instead.                                                                                                                                                                                  |
| **`get_entity_details` paginates columns**           | Wide entities return paged columns; custom properties (`extension`) are now surfaced.                                                                                                                                                                                            |
| **`get_entity_lineage` returns full SQL**            | Transformation SQL is no longer truncated; size is controlled by returning fewer edges.                                                                                                                                                                                          |
| **`create_*` tools return a compact entity**         | Instead of the full entity.                                                                                                                                                                                                                                                      |
| **Name term queries must be lowercased**             | `fullyQualifiedName` is indexed with a lowercase normalizer, so `{"terms": {"fullyQualifiedName": ["DailyActiveUsers"]}}` silently matches nothing.                                                                                                                              |

### Other MCP changes

* Tools are annotated with title, read-only, destructive and open-world hints; `create_lineage` is
  marked destructive.
* `get_entity_details` is authorized against the **resolved** entity.
* Create tools can set custom properties, and create-overwrites are re-authorized.
* SAML SSO is supported in the MCP OAuth flow; public clients are no longer issued a client secret.
* Content negotiation prefers `application/json` when the client accepts both JSON and SSE.
* Tool-call usage is tracked via `/v1/mcp/usage`.

<Tip>
  Re-run your MCP client against 2.0 before rolling out. Anything that counted results with a `size: 0`
  aggregation query, or paged with a bespoke offset, must change.
</Tip>

## CSV import and export become tracked background jobs

<Note>
  **Behavioural.** Affects CSV automation and the UI.
</Note>

`background_jobs` gains `progress`, `total`, `result`, `error`, `message`, `cancelRequested` and
`completedAt`, plus a new `background_job_logs` table. `jobType` gains `CSV_IMPORT`, `CSV_EXPORT` and
`AUDIT_EXPORT`; `status` gains `CANCELLED`.

| Endpoint                                 | Purpose                                   |
| ---------------------------------------- | ----------------------------------------- |
| `GET /v1/csvAsyncJobs`                   | List the caller's jobs                    |
| `GET /v1/csvAsyncJobs/{jobId}`           | Job status                                |
| `GET /v1/csvAsyncJobs/{jobId}/result`    | Download the produced CSV                 |
| `PUT /v1/csvAsyncJobs/{jobId}/cancel`    | Request cancellation                      |
| `GET /v1/csv/documentation/{entityType}` | Machine-readable CSV column documentation |
| `GET /v1/audit/logs/export/{jobId}`      | Audit log export result                   |

In 1.13 async CSV progress was delivered **only** over WebSocket — a client without a live socket had
no way to observe the job. 2.0 makes jobs pollable and downloadable, and the UI surfaces them in a
**Background jobs** tray.

Async entity **restore** is also available via `PUT /v1/{entityType}/restore?async=true`, and entity
metrics gain full CSV import and export support.

## Concurrency limits for background fan-out

<Info>
  **Additive.** New `openmetadata.yaml` block.
</Info>

```yaml theme={null}
asyncOperations:
  maxConcurrentDbTasks: ${ASYNC_MAX_CONCURRENT_DB_TASKS:-25}
  maxConcurrentRdfWrites: ${ASYNC_MAX_CONCURRENT_RDF_WRITES:-8}
  dataInsightsMaxConcurrentDbTasks: ${DATA_INSIGHTS_MAX_CONCURRENT_DB_TASKS:-16}
```

Prevents background fan-out from exhausting the request connection pool. Tune down if you see
connection-pool starvation during reindex or Data Insights runs.

## Search & vector infrastructure

<Info>
  **Additive.**
</Info>

| Change                              | Detail                                                             |
| ----------------------------------- | ------------------------------------------------------------------ |
| Native Elasticsearch vector search  | In addition to OpenSearch                                          |
| Google Gemini embedding provider    | New provider option                                                |
| Denormalised chunk documents        | Versioned rollout for multi-chunk hybrid ranking                   |
| Staged, generation-based recreate   | For the vector chunk index                                         |
| `GET /v1/search/vector/fingerprint` | Inspect the vector index fingerprint                               |
| `knnNumCandidatesMultiplier`        | `num_candidates = max(k × multiplier, 100)`, default `2`           |
| NLQ `filterExtractor` block         | Cache size, TTL and prompt sample limits for NLQ filter extraction |

## Cache

<Info>
  **Additive.** New admin endpoints: `GET /v1/system/cache/keys`, `POST /v1/system/cache/invalidate` and
  `POST /v1/system/cache/invalidate/entity`. The cache default is unchanged — set `CACHE_PROVIDER=redis`
  to enable the Redis L2 cache, which falls back to a no-op provider if Redis is unreachable at startup.
</Info>