Azure / Azure/azure-sdk-for-java

[azure-ai-contentunderstanding] updateAnalyzer docs should clarify which properties are updatable

Open
#48,469 0 comments 0 reactions 0 assignees View on GitHub
Cognitive - Content Understanding
Dominant language
Java
Stars
2.6k
Forks
2.2k
Avg merge
2d 8h
Merged PRs (30d)
178

Description

## Description

The `updateAnalyzer` method in `ContentUnderstandingClient` currently has documentation that says only "Update analyzer properties" without specifying **which** properties can actually be updated.

The underlying REST API uses `PATCH` with `application/merge-patch+json`, and **only `description` and `tags`** are accepted by the service. All other properties (`models`, `fieldSchema`, `config`, `baseAnalyzerId`, `dynamicFieldSchema`, `processingLocation`, `knowledgeSources`) are create-only — they are silently ignored by the server even though it returns HTTP 200.

## Requested Improvements

1. **API doc (Javadoc)**: Add documentation to `updateAnalyzer` listing the updatable properties and noting that other properties require `createAnalyzer` with `allowReplace(true)`.

2. **Samples**: If an update analyzer sample exists, add a note explaining that only `description` and `tags` are updatable via this method, and reference `createAnalyzer` with `allowReplace(true)` for changing `models`, `fieldSchema`, etc.

## Updatable Properties

| Property | Updatable via `updateAnalyzer` (PATCH)? |
|---|---|
| `description` | **Yes** |
| `tags` | **Yes** |
| `models` | No — silently ignored |
| `fieldSchema` | No — silently ignored |
| `config` | No — silently ignored |
| `baseAnalyzerId` | No — silently ignored |
| `dynamicFieldSchema` | No — silently ignored |
| `processingLocation` | No — silently ignored |
| `knowledgeSources` | No — silently ignored |

## Workaround

To change create-only properties on an existing analyzer, use `createAnalyzer` with `allowReplace(true)`. This calls `PUT` (full resource replacement) instead of `PATCH`.

## Related

- Azure/azure-sdk-for-net#57215 — customer report of `UpdateAnalyzerAsync` not updating `models`
- Azure/azure-sdk-for-net#57231 — .NET documentation issue

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.