feat(entities): choice-set awareness for query engine

[UIPath-Harshit]

Summary

• Fix choiceset_id alias mismatch on EntityField so the SDK populates the field correctly
• Add resolve_choice_sets query option to v1/query/execute so the server returns labels instead of NumberIds
• Add UNSUPPORTED_CONSTRUCT error category so retry loops stop on impossible query shapes

Changes

File	What
entities.py	Fix choiceset_id alias: "choicesetId" → AliasChoices("choiceSetId", "choicesetId", "ChoiceSetId")
_entity_data_service.py	resolve_choice_sets param through to _query_entity_records_spec. _validate_sql_query raises DataFabricSqlValidationError with stable codes
_entities_service.py	Public facade gets resolve_choice_sets kwarg
_datafabric_error.py	DataFabricSqlValidationError class, DataFabricError.from_exception() unified extractor, is_unsupported_construct property
datafabric_error_codes.py	UNSUPPORTED_CONSTRUCT category with 4 codes

Test plan

• Validated with 17/17 live agent queries against choice-set entities on alpha
• Run existing SDK unit tests

Ref: DS-8647

🤖 Generated with Claude Code

[github-actions]

🚨 Heads up: uipath-integrations cross-tests are FAILING 🚨

Your changes may break one or more integrations in uipath-integrations-python:

• uipath-openai-agents
• uipath-google-adk
• uipath-agent-framework
• uipath-llamaindex
• uipath-pydantic-ai

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

[github-actions]

🚨 Heads up: uipath-langchain cross-tests are FAILING 🚨

Your changes may break the uipath-langchain-python integration.

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

🟢 Approval recommended

The changes are cohesive, covered by targeted unit tests, and the updated API surface/error classification appears consistent and non-breaking.

Pull request overview

Adds choice-set awareness and richer client-side error classification to the Data Fabric entity query path in uipath-platform, improving both query result usability (labels for choice-set fields) and downstream error handling (stable, actionable categories/codes).

Changes:

• Fix FieldMetadata.choiceset_id parsing/serialization by accepting multiple server casing variants via AliasChoices.
• Add resolve_choice_sets option to entity federated query methods and request-body construction (queryOptions.resolveChoiceSets).
• Introduce DataFabricSqlValidationError + UNSUPPORTED_CONSTRUCT classification and a unified DataFabricError.from_exception() extractor for client/server failures.

File summaries

File	Description
packages/uipath/uv.lock	Bumps editable uipath-platform version reference to 0.2.28.
packages/uipath-platform/uv.lock	Updates uipath-platform lock entry to 0.2.28.
packages/uipath-platform/pyproject.toml	Bumps package version to 0.2.28.
packages/uipath-platform/src/uipath/platform/entities/entities.py	Makes FieldMetadata.choiceset_id resilient to server casing/alias variants and standardizes dump alias.
packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py	Threads resolve_choice_sets through query methods/spec builder; raises structured validation errors with stable codes.
packages/uipath-platform/src/uipath/platform/entities/_entities_service.py	Exposes resolve_choice_sets as a public kwarg on sync/async query APIs and documents behavior.
packages/uipath-platform/src/uipath/platform/errors/_datafabric_error.py	Adds UNSUPPORTED_CONSTRUCT support, from_exception() unifier, and DataFabricSqlValidationError carrier type.
packages/uipath-platform/src/uipath/platform/errors/datafabric_error_codes.py	Introduces UNSUPPORTED_CONSTRUCT category + code set and updates classification table.
packages/uipath-platform/tests/services/test_entities_service.py	Adds coverage for resolveChoiceSets request option and FieldMetadata choice-set alias parsing/serialization.
packages/uipath-platform/tests/errors/test_datafabric_errors.py	Adds tests for new error codes/category behavior and DataFabricError.from_exception() extraction.

Review details

• Files reviewed: 8/10 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.