From 824c6f2ea57bff8279c2bd9aa021ecf04282a157 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 09:33:54 +0000 Subject: [PATCH] Document RETURN JSON response objects with id fields and element shapes - Add "Response structure" section to output_values.mdx explaining single-element vs. array return shapes and element object shapes (node, edge, vector) including the id field - Add id field to all full-element JSON output examples in output_values.mdx - Add JSON output blocks to all CRUD page examples: addN.mdx, addE.mdx, addV.mdx, updating.mdx, deleting.mdx - Document edge return shape (id, from, to, plus properties) - Document vector return shape (id plus metadata properties) - Add note clarifying that projection omits id unless explicitly requested, while exclusion preserves id https://claude.ai/code/session_011iZUtHW8avKg7x4AbKNH8t --- documentation/hql/create/addE.mdx | 32 +++++++++++++++ documentation/hql/create/addN.mdx | 30 ++++++++++++++ documentation/hql/create/addV.mdx | 34 ++++++++++++++++ documentation/hql/deleting.mdx | 30 ++++++++++++++ documentation/hql/output_values.mdx | 63 ++++++++++++++++++++++++----- documentation/hql/updating.mdx | 10 +++++ 6 files changed, 189 insertions(+), 10 deletions(-) diff --git a/documentation/hql/create/addE.mdx b/documentation/hql/create/addE.mdx index 1c939e7..0ee1dc2 100644 --- a/documentation/hql/create/addE.mdx +++ b/documentation/hql/create/addE.mdx @@ -46,6 +46,16 @@ E::Follows { To: User, } ``` + +```json Output +{ + "follows": { + "id": "a1b2c3d4-1de9-5gbf-9247-c51604803082", + "from": "c2ca233f-0cd8-4fae-8136-b40593792071", + "to": "d3db344g-0cd8-4fae-8136-b40593792071" + } +} +``` @@ -249,6 +259,18 @@ E::Friends { } } ``` + +```json Output +{ + "friendship": { + "id": "b2c3d4e5-1de9-5gbf-9247-c51604803082", + "from": "c2ca233f-0cd8-4fae-8136-b40593792071", + "to": "d3db344g-0cd8-4fae-8136-b40593792071", + "since": "2024-01-15", + "strength": 0.85 + } +} +``` Here's how to run the query using the SDKs or curl @@ -443,6 +465,16 @@ E::Follows { To: User, } ``` + +```json Output +{ + "follows": { + "id": "a1b2c3d4-1de9-5gbf-9247-c51604803082", + "from": "c2ca233f-0cd8-4fae-8136-b40593792071", + "to": "d3db344g-0cd8-4fae-8136-b40593792071" + } +} +``` Here's how to run the query using the SDKs or curl diff --git a/documentation/hql/create/addN.mdx b/documentation/hql/create/addN.mdx index 0e90460..0d00bcb 100644 --- a/documentation/hql/create/addN.mdx +++ b/documentation/hql/create/addN.mdx @@ -32,6 +32,14 @@ N::User { email: String, } ``` + +```json Output +{ + "empty_user": { + "id": "c2ca233f-0cd8-4fae-8136-b40593792071" + } +} +``` Here's how to run the query using the SDKs or curl @@ -124,6 +132,17 @@ N::User { email: String, } ``` + +```json Output +{ + "user": { + "id": "c2ca233f-0cd8-4fae-8136-b40593792071", + "name": "Alice", + "age": 25, + "email": "alice@example.com" + } +} +``` Here's how to run the query using the SDKs or curl @@ -242,6 +261,17 @@ N::User { email: String, } ``` + +```json Output +{ + "predefined_user": { + "id": "d3db344g-1de9-5gbf-9247-c51604803082", + "name": "Alice Johnson", + "age": 30, + "email": "alice@example.com" + } +} +``` diff --git a/documentation/hql/create/addV.mdx b/documentation/hql/create/addV.mdx index a18e131..dfe26e9 100644 --- a/documentation/hql/create/addV.mdx +++ b/documentation/hql/create/addV.mdx @@ -38,6 +38,14 @@ QUERY InsertVector (vector: [F64]) => // it uses [F64] by default V::Document {} ``` + +```json Output +{ + "vector_node": { + "id": "f5e6d7c8-2ef0-6hcg-0358-d62715914193" + } +} +``` Here's how to run the query using the SDKs or curl @@ -140,6 +148,16 @@ V::Document { created_at: Date } ``` + +```json Output +{ + "vector_node": { + "id": "f5e6d7c8-2ef0-6hcg-0358-d62715914193", + "content": "Quick brown fox", + "created_at": "2024-06-15T12:00:00Z" + } +} +``` Here's how to run the query using the SDKs or curl @@ -274,6 +292,12 @@ E::User_to_Document_Embedding { To: Document, } ``` + +```json Output +{ + "result": "Success" +} +``` Here's how to run the query using the SDKs or curl @@ -439,6 +463,16 @@ V::Document { } ``` +```json Output +{ + "vector_node": { + "id": "a1b2c3d4-3fg1-7hij-1469-e73826025204", + "content": "Quick summary of a meeting", + "created_at": "2024-06-15T12:00:00Z" + } +} +``` + ```.env Environment Variables (.env) OPENAI_API_KEY=your_api_key ``` diff --git a/documentation/hql/deleting.mdx b/documentation/hql/deleting.mdx index 17a9fe6..1cabaf1 100644 --- a/documentation/hql/deleting.mdx +++ b/documentation/hql/deleting.mdx @@ -41,6 +41,12 @@ E::Follows { To: User, } ``` + +```json Output +{ + "result": "Removed user node" +} +``` Here's how to run the query using the SDKs or curl @@ -201,6 +207,12 @@ E::Follows { To: User, } ``` + +```json Output +{ + "result": "Removed outgoing neighbors" +} +``` Here's how to run the query using the SDKs or curl @@ -411,6 +423,12 @@ E::Follows { To: User, } ``` + +```json Output +{ + "result": "Removed incoming neighbors" +} +``` Here's how to run the query using the SDKs or curl @@ -621,6 +639,12 @@ E::Follows { To: User, } ``` + +```json Output +{ + "result": "Removed outgoing edges" +} +``` Here's how to run the query using the SDKs or curl @@ -831,6 +855,12 @@ E::Follows { To: User, } ``` + +```json Output +{ + "result": "Removed incoming edges" +} +``` Here's how to run the query using the SDKs or curl diff --git a/documentation/hql/output_values.mdx b/documentation/hql/output_values.mdx index 8548f97..a47e4ca 100644 --- a/documentation/hql/output_values.mdx +++ b/documentation/hql/output_values.mdx @@ -21,6 +21,49 @@ projected properties, aggregations, literals, or choose to return nothing at all When using the [Python SDK](../sdks/helix-py), the output values are wrapped in an array for multiple query calls, so you will need to access the first element of the array to get the result of the first call. +## Response structure + +Every HelixQL response is a JSON object whose top-level keys are the binding names +used in `RETURN`. The value for each key depends on how many elements the binding holds: + +| Binding selects | Example syntax | Value shape | +|----------------------------|-----------------------------|---------------------| +| Multiple elements | `N` | Array of objects | +| Single element (by ID) | `N(user_id)` | Single object | +| Traversal results | `user::Out` | Array of objects | +| Scalar / aggregation | `N::COUNT` | Single value | + +### Element object shapes + +Every element returned by HelixDB includes an `id` field (a UUID string) alongside its +schema-defined properties. + +**Node** +```json +{ "id": "c2ca233f-...", "name": "Alice", "age": 25, "email": "alice@example.com" } +``` + +**Edge** — includes `from` and `to` fields referencing the connected node IDs, plus +any properties defined in the `Properties` block of the schema. +```json +{ "id": "a1b2c3d4-...", "from": "c2ca233f-...", "to": "d3db344g-...", "since": "2024-01-15" } +``` + +**Vector** — includes metadata properties defined in the schema. +```json +{ "id": "f5e6d7c8-...", "content": "Quick brown fox", "created_at": "2024-01-15T00:00:00Z" } +``` + + +When you use [property projection](../hql/properties/property-access) (`::{ name, age }`), +only the fields you list are returned — `id` is **not** included unless you explicitly +request it (e.g. `::{ userID: ::ID, name }`). When you use +[property exclusion](../hql/properties/property-exclusion) (`::!{ email }`), `id` is still +included because it is not a schema-defined property. + + +--- + ## Returning bindings Return any previously bound value from your traversal. @@ -43,9 +86,9 @@ N::User { ```json Output { "users": [ - { "name": "Alice", "age": 25, "email": "alice@example.com" }, - { "name": "Bob", "age": 30, "email": "bob@example.com" }, - { "name": "Charlie", "age": 28, "email": "charlie@example.com" }, + { "id": "c2ca233f-0cd8-4fae-8136-b40593792071", "name": "Alice", "age": 25, "email": "alice@example.com" }, + { "id": "d3db344g-1de9-5gbf-9247-c51604803082", "name": "Bob", "age": 30, "email": "bob@example.com" }, + { "id": "e4ec455h-2ef0-6hcg-0358-d62715914193", "name": "Charlie", "age": 28, "email": "charlie@example.com" } ] } ``` @@ -82,10 +125,10 @@ E::User_to_Post { ```json Output { - "user": {"name": "Alice", "age": 25, "email": "alice@example.com"}, - "posts": [ - {"title": "My First Post", "content": "This is my first blog post!"}, - ..., + "user": {"id": "c2ca233f-0cd8-4fae-8136-b40593792071", "name": "Alice", "age": 25, "email": "alice@example.com"}, + "posts": [ + {"id": "d3db344g-1de9-5gbf-9247-c51604803082", "title": "My First Post", "content": "This is my first blog post!"}, + ... ] } ``` @@ -172,9 +215,9 @@ N::User { ```json Output { "users": [ - { "name": "Alice", "age": 25 }, - { "name": "Bob", "age": 30 }, - { "name": "Charlie", "age": 28 } + { "id": "c2ca233f-0cd8-4fae-8136-b40593792071", "name": "Alice", "age": 25 }, + { "id": "d3db344g-1de9-5gbf-9247-c51604803082", "name": "Bob", "age": 30 }, + { "id": "e4ec455h-2ef0-6hcg-0358-d62715914193", "name": "Charlie", "age": 28 } ] } ``` diff --git a/documentation/hql/updating.mdx b/documentation/hql/updating.mdx index 812f54a..1824070 100644 --- a/documentation/hql/updating.mdx +++ b/documentation/hql/updating.mdx @@ -37,6 +37,16 @@ N::Person { age: U32, } ``` + +```json Output +{ + "updated": { + "id": "c2ca233f-0cd8-4fae-8136-b40593792071", + "name": "Alice Johnson", + "age": 26 + } +} +```