# Azure Search Documents

> Post-regeneration customization guide for azure-search-documents SDK. Covers error diagnosis, customization patterns, and search-specific fixes after tsp-client update. WHEN: regenerate azure-search-documents; fix azure-search-documents build errors; azure-search-documents customization errors; azure-search-documents API version update; update azure-search-documents service version.

- Skill: `azure-azure-sdk-for-java/azure-search-documents` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add azure-azure-sdk-for-java/azure-search-documents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azure-azure-sdk-for-java/azure-search-documents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Azure (https://skillmd.com/u/azure-azure-sdk-for-java)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/azure-azure-sdk-for-java/azure-search-documents

---


# azure-search-documents -- Package Skill

> The `generate-sdk-locally` shared skill handles generation, build, test, and customization workflows -- including running `azsdk_customized_code_update` when builds fail. **This skill activates after those tools have been tried.** It covers what they can't solve: search-specific error diagnosis, customization fragility patterns, and convenience layer design.

## Common Pitfalls

- **Never hand-edit generated files.** Files with `// Code generated by Microsoft (R) TypeSpec Code Generator.` are overwritten on every `tsp-client update`. All modifications go through `SearchCustomizations.java`.
- **Check `SearchCustomizations.java` FIRST when generated files have errors.** The customizations run during generation and can produce broken output if the generated code structure changed. The most common culprits:
  - `hideWithResponseBinaryDataApis()` -- rewires method bodies across packages, can create cross-package import mismatches
  - `includeOldApiVersions()` -- can duplicate enum constants the generator now produces
  - `addSearchAudienceScopeHandling()` -- may fail if builder structure changed
- **Methods without `@Generated` in generated files are hand-written.** These are convenience wrappers that the generator preserves but does NOT update. After regeneration, you must manually update them to match any changed generated signatures. Look at how the `@Generated` methods in the same file were updated as a pattern to follow.
- **`includeOldApiVersions` can create duplicate enum constants.** If the generator starts producing a version that was previously only in the customization list, you get a compilation error. Remove the version from the customization list.

## After Regeneration -- Diagnose and Fix Build Errors

Categorize each compilation error:

| Error location | What it means | Where to fix |
|---|---|---|
| Generated file, `@Generated` method | Customization produced broken output | **Fix `SearchCustomizations.java`** -- update AST queries to match new generated code |
| Generated file, method WITHOUT `@Generated` | Hand-written wrapper references changed generated types | **Fix the hand-written method** -- match the pattern used by `@Generated` methods in the same file |
| Hand-written file (`SearchUtils.java`, `FieldBuilder.java`, batching, tests) | References removed/renamed generated types | **Fix the hand-written file** |

## Verify Service Version

`SearchServiceVersion.java` is generated but customized by `SearchCustomizations.java`.

1. Check `getLatest()` returns the new version
2. In `includeOldApiVersions()`:
   - **Remove** any version the generator now produces (prevents duplicates)
   - **Add** the previous latest version if not already produced by the generator
3. Verify all expected old versions are present

## Detect Breaking Changes

```bash
# Removed/renamed public types
git diff --name-status HEAD -- sdk/search/azure-search-documents/src/main/java/ | grep "^D"
```

Watch for: removed types, renamed constants (need `@Deprecated` aliases), changed property types, removed method overloads.

## Test Recording Notes

If test recordings are stale, update `assets.json` and re-record. Remove tests for features that no longer exist in the API.

## References

| File | Contents |
|---|---|
| [references/architecture.md](references/architecture.md) | Source layout, generated vs custom split, key files, packages |
| [references/customizations.md](references/customizations.md) | Per-method customization guide, JavaParser patterns, update triggers |