feat(entities): relationships_as_scalar query option for FK joins#1818
Conversation
github-actions
Bot
added
test:uipath-langchain
There was a problem hiding this comment.
Pull request overview
This PR updates the Data Fabric “federated SQL query” API surface in EntitiesService to use an explicit relationships_as_scalar: bool option (sent as queryOptions.relationshipsAsScalar in the request body) instead of the previous x-uipath-source header approach, enabling FK relationship fields to be treated as scalar IDs for join scenarios.
Changes:
- Replace the
sourceparameter/header with arelationships_as_scalarboolean that conditionally addsqueryOptions.relationshipsAsScalarto the query/execute request body. - Thread the option through both sync and async query paths and update docstrings accordingly.
- Update tests to assert the new request-body behavior and bump
uipath-platformto0.2.11(lockfiles regenerated).
Reviewed changes
Copilot reviewed 4 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/uipath/uv.lock | Bumps the editable uipath-platform version to 0.2.11. |
| packages/uipath-platform/uv.lock | Bumps the uipath-platform package version to 0.2.11. |
| packages/uipath-platform/tests/services/test_entities_service.py | Replaces source-header assertions with request-body queryOptions.relationshipsAsScalar assertions (sync + async). |
| packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py | Implements conditional queryOptions.relationshipsAsScalar emission and removes the source header plumbing. |
| packages/uipath-platform/src/uipath/platform/entities/_entities_service.py | Exposes relationships_as_scalar on the public API and updates docstrings. |
| packages/uipath-platform/pyproject.toml | Version bump to 0.2.11. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| def query_entity_records( | ||
| self, sql_query: str, source: Optional[str] = None | ||
| self, sql_query: str, relationships_as_scalar: bool = False | ||
| ) -> List[Dict[str, Any]]: |
There was a problem hiding this comment.
Fixed in 0cbad36 — made relationships_as_scalar keyword-only (*) on both query_entity_records and query_entity_records_async, so an old positional source call now raises TypeError instead of silently coercing the truthy string. Added test_query_entity_records_flag_is_keyword_only to guard it.
| async def query_entity_records_async( | ||
| self, sql_query: str, source: Optional[str] = None | ||
| self, sql_query: str, relationships_as_scalar: bool = False | ||
| ) -> List[Dict[str, Any]]: |
There was a problem hiding this comment.
Fixed in 0cbad36 — made relationships_as_scalar keyword-only (*) on both query_entity_records and query_entity_records_async, so an old positional source call now raises TypeError instead of silently coercing the truthy string. Added test_query_entity_records_flag_is_keyword_only to guard it.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 80f208188b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @traced(name="entity_query_records", run_type="uipath") | ||
| def query_entity_records( | ||
| self, sql_query: str, source: Optional[str] = None | ||
| self, sql_query: str, relationships_as_scalar: bool = False |
There was a problem hiding this comment.
With this public signature, an existing caller using the previously supported positional source argument, e.g. query_entity_records(sql, "LOW_CODE_AGENT"), is still accepted because non-empty strings are truthy; it now sends queryOptions.relationshipsAsScalar and drops x-uipath-source instead of failing. Since the commit removes the keyword form too, make the new flag keyword-only (and/or validate it is a bool) for both sync and async wrappers so old positional calls don't silently execute with different semantics.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 0cbad36 — made relationships_as_scalar keyword-only (*) on both query_entity_records and query_entity_records_async, so an old positional source call now raises TypeError instead of silently coercing the truthy string. Added test_query_entity_records_flag_is_keyword_only to guard it.
0cbad36 to
eb6bb96
Compare
Replaces the query/execute `source` header param with an explicit `relationships_as_scalar` bool that sets `queryOptions.relationshipsAsScalar` in the request body (FQS contract, UiPath/CommonEntityPlatform#5611). When set, relationship (FK) fields are typed as their scalar id so a query can join on `relationshipField = Other.Id`. Optional and backward-compatible (default False). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Prevents a released positional `source` call (`query_entity_records(sql, "LOW_CODE_AGENT")`) from silently coercing the truthy string into `relationships_as_scalar=True`; such calls now raise TypeError. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
0.2.11 was released to PyPI from main (#1822) without this change, so this PR ships as 0.2.12. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
504bc14 to
ae80986
Compare
0.2.11 is published without the relationships_as_scalar option (it still carries the old source param); the option lands in 0.2.12 (UiPath/uipath-python#1818). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
What
Replaces the
sourceheader param on the Data Fabric query API with an explicitrelationships_as_scalar: booloption onEntitiesService.query_entity_records[_async]. WhenTrue, the request sendsqueryOptions.relationshipsAsScalarin thev1/query/executebody so FQS types relationship (FK) fields as their scalar id — letting a query join onrelationshipField = Other.Id(FQS contract, UiPath/CommonEntityPlatform#5611). Optional and backward-compatible: defaultFalseomitsqueryOptionsand preserves prior behaviour.How
_query_entity_records_specaddsbody["queryOptions"] = {"relationshipsAsScalar": True}only when the flag is set; the removedsourcepath (and itsx-uipath-sourceheader +HEADER_SOURCEimport) is gone.query_entity_records[_async]→_query_entities_for_records[_async]→ the shared spec builder, sync and async identically.uipath-platform0.2.10 → 0.2.11; both lockfiles regenerated.Security
sql_queryvalidation is unchanged.routingContext(folder-scoped routing derived fromfolders_map) is untouched; the flag only changes FK column typing, not tenant/folder scoping. Removing the header weakens nothing —BaseService.requeststill injects auth/trace/routing headers.Tests
source-header tests with body-assertion tests: sync + asyncqueryOptions.relationshipsAsScalar == Truewhen set, andqueryOptionsomitted by default.test_entities_service.py, 153 passed). Changed-code coverage: the edited query methods are 100% covered (whole-file 94.7% / 99.4%). ruff + ruff format + mypy clean.Review triage
Independent adversarial review returned P0/P1 count: 0.
test_query_entity_records_async_sets_relationships_as_scalar_option.body = ...get("json") or call_args[1].get("json")fallback is dead — left as-is to match the existing idiom in the sibling routing tests; cosmetic, no behaviour impact.🤖 Generated with Claude Code
Manual verification (local end-to-end)
Verified through a low-code agent run (
uipath-robot) against a local QueryEngine build of UiPath/CommonEntityPlatform#5611 (QE isn't live on alpha yet), over folder-scoped Data Fabric entitiesSalesOrderSpace(OrderNumber, Amount, account → AccountSpace)andAccountSpace(Id, Name). The SDK sentqueryOptions.relationshipsAsScalar: trueonv1/query/execute; QE returned 200 in both cases.SELECT OrderNumber, Amount, account FROM SalesOrderSpace: theaccountrelationship field returns as a scalar id (GUID string),nullwhen unset — notVARIANT/expanded object.SELECT s.OrderNumber, s.Amount, a.Id, a.Name FROM SalesOrderSpace s LEFT JOIN AccountSpace a ON a.Id = s.account: validates and executes (two per-entity fragments federated → SQLite join), correct pairing (SO-3001→Acme Corp, SO-3002→Globex, SO-3003→null via LEFT JOIN). Without the scalar option this join is rejected as<VARIANT> = <VARCHAR>.