Document HelixQL response structure and add JSON output examples

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"
+  }
+}
+```
 </CodeGroup>
 
 
@@ -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
+  }
+}
+```
 </CodeGroup>
 
 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"
+  }
+}
+```
 </CodeGroup>
 
 Here's how to run the query using the SDKs or curl

documentation/hql/create/addN.mdx

@@ -32,6 +32,14 @@ N::User {
     email: String,
 }
 ```
+
+```json Output
+{
+  "empty_user": {
+    "id": "c2ca233f-0cd8-4fae-8136-b40593792071"
+  }
+}
+```
 </CodeGroup>
 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"
+  }
+}
+```
 </CodeGroup>
 
 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"
+  }
+}
+```
 </CodeGroup>
 
 

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"
+  }
+}
+```
 </CodeGroup>
 
 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"
+  }
+}
+```
 </CodeGroup>
 
 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"
+}
+```
 </CodeGroup>
 
 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
 ```

documentation/hql/deleting.mdx

@@ -41,6 +41,12 @@ E::Follows {
     To: User,
 }
 ```
+
+```json Output
+{
+  "result": "Removed user node"
+}
+```
 </CodeGroup>
 
 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"
+}
+```
 </CodeGroup>
 
 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"
+}
+```
 </CodeGroup>
 
 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"
+}
+```
 </CodeGroup>
 
 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"
+}
+```
 </CodeGroup>
 
 Here's how to run the query using the SDKs or curl

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.
 </Warning>
 
+## 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<User>`                   | Array of objects    |
+| Single element (by ID)     | `N<User>(user_id)`          | Single object       |
+| Traversal results          | `user::Out<Follows>`        | Array of objects    |
+| Scalar / aggregation       | `N<User>::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** &mdash; 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** &mdash; includes metadata properties defined in the schema.
+```json
+{ "id": "f5e6d7c8-...", "content": "Quick brown fox", "created_at": "2024-01-15T00:00:00Z" }
+```
+
+<Note>
+When you use [property projection](../hql/properties/property-access) (`::{ name, age }`),
+only the fields you list are returned &mdash; `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.
+</Note>
+
+---
+
 ## 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 }
   ]
 }
 ```

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
+  }
+}
+```
 </CodeGroup>
 
 <Info>