Azure / Azure/azure-sdk-for-python

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

Open
#45,789 0 comments 1 reaction 2 assignees Claimed by @yungshinlintw View on GitHub
Cognitive - Content Understanding
Dominant language
Python
Stars
5.6k
Forks
3.4k
Avg merge
1d 21h
Merged PRs (30d)
193

Description

## Description

The `update_analyzer` 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`, `field_schema`, `config`, `base_analyzer_id`, `dynamic_field_schema`, `processing_location`, `knowledge_sources`) are create-only — they are silently ignored by the server even though it returns HTTP 200.

## Requested Improvements

1. **API doc (docstring)**: Add documentation to `update_analyzer` listing the updatable properties and noting that other properties require `begin_create_analyzer` with `allow_replace=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 `begin_create_analyzer` with `allow_replace=True` for changing `models`, `field_schema`, etc.

## Updatable Properties

| Property | Updatable via `update_analyzer` (PATCH)? |
|---|---|
| `description` | **Yes** |
| `tags` | **Yes** |
| `models` | No — silently ignored |
| `field_schema` | No — silently ignored |
| `config` | No — silently ignored |
| `base_analyzer_id` | No — silently ignored |
| `dynamic_field_schema` | No — silently ignored |
| `processing_location` | No — silently ignored |
| `knowledge_sources` | No — silently ignored |

## Workaround

To change create-only properties on an existing analyzer, use `begin_create_analyzer` with `allow_replace=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
- Azure/azure-sdk-for-java#48469 — Java documentation issue
- Azure/azure-sdk-for-js#37728 — JavaScript 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.