Document HelixQL response structure and add JSON output examples by xav-db · Pull Request #47 · HelixDB/helix-ql-docs

xav-db · 2026-02-13T11:11:45Z

Summary

This PR enhances the HelixQL documentation by adding comprehensive information about response structures and including JSON output examples throughout the documentation. These changes help users understand the format and shape of data returned by HelixQL queries.

Key Changes

Added "Response structure" section to output_values.mdx that explains:
- How HelixQL responses are structured as JSON objects with binding names as top-level keys
- A reference table showing different binding types and their corresponding value shapes (arrays vs single objects)
- Detailed element object shapes for Nodes, Edges, and Vectors with example JSON
- Clarification on how property projection and exclusion affect the id field in responses
Updated all query examples across multiple documentation files to include realistic JSON output examples:
- output_values.mdx: Added id fields to all response examples and updated existing outputs
- addN.mdx: Added JSON output examples for node creation queries
- addE.mdx: Added JSON output examples for edge creation queries with id, from, and to fields
- addV.mdx: Added JSON output examples for vector creation queries
- updating.mdx: Added JSON output example for update operations
- deleting.mdx: Added JSON output examples for delete operations
Standardized response format by including id fields (UUID strings) in all example outputs, reflecting the actual behavior of HelixDB

Notable Details

All example JSON outputs now include realistic UUID-format id values
Edge examples consistently show from and to fields referencing node IDs
Vector examples include metadata properties like created_at
The new response structure documentation clarifies the distinction between single objects and arrays based on query binding types
Documentation now accurately reflects that id is always included unless explicitly excluded via property projection

https://claude.ai/code/session_011iZUtHW8avKg7x4AbKNH8t

Greptile Overview

Greptile Summary

This PR significantly improves the HelixQL documentation by adding comprehensive JSON output examples and detailed response structure documentation. The additions help users understand the format and shape of data returned by HelixQL queries.

Key improvements:

Added "Response structure" section in output_values.mdx explaining how JSON responses are structured with binding names as top-level keys
Added reference table showing binding types and their value shapes (arrays vs single objects)
Documented element object shapes for Nodes, Edges, and Vectors with proper field structures
Added JSON output examples across all query operation files (addN.mdx, addE.mdx, addV.mdx, updating.mdx, deleting.mdx)
Clarified how property projection and exclusion affect the id field in responses

Issues found:

Multiple example IDs contain invalid hexadecimal characters ('g', 'h', 'i', 'j') that make them syntactically incorrect as UUIDs. Valid UUIDs should only contain characters 0-9 and a-f. These need to be corrected to use valid hex characters.

Important Files Changed

Filename	Overview
documentation/hql/output_values.mdx	Added comprehensive response structure documentation and updated JSON examples to include `id` fields. Contains invalid UUID formats with non-hexadecimal characters (g, h, i, j).
documentation/hql/create/addE.mdx	Added JSON output examples for edge creation showing `id`, `from`, and `to` fields. Contains invalid UUID with 'g' character.
documentation/hql/create/addN.mdx	Added JSON output examples for node creation with `id` fields. Contains invalid UUID with 'g' character.
documentation/hql/create/addV.mdx	Added JSON output examples for vector creation with `id` and metadata fields. Contains invalid UUIDs with non-hexadecimal characters (g, h, i, j).

_{Last reviewed commit: 824c6f2}

- 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

greptile-apps

_{6 files reviewed, 9 comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-13T11:15:56Z

+```json Output
+{
+  "predefined_user": {
+    "id": "d3db344g-1de9-5gbf-9247-c51604803082",


the character 'g' in this ID value is not valid hexadecimal (valid: 0-9, a-f). Replace 'g' with a valid hex character like 'f'.

greptile-apps · 2026-02-13T11:15:57Z

+  "follows": {
+    "id": "a1b2c3d4-1de9-5gbf-9247-c51604803082",
+    "from": "c2ca233f-0cd8-4fae-8136-b40593792071",
+    "to": "d3db344g-0cd8-4fae-8136-b40593792071"


the character 'g' in the to field is not valid hexadecimal. Replace with a valid character (0-9, a-f).

greptile-apps · 2026-02-13T11:15:58Z

+  "friendship": {
+    "id": "b2c3d4e5-1de9-5gbf-9247-c51604803082",
+    "from": "c2ca233f-0cd8-4fae-8136-b40593792071",
+    "to": "d3db344g-0cd8-4fae-8136-b40593792071",


the character 'g' in the to field is not valid hexadecimal. Replace with a valid character (0-9, a-f).

greptile-apps · 2026-02-13T11:15:59Z

+  "follows": {
+    "id": "a1b2c3d4-1de9-5gbf-9247-c51604803082",
+    "from": "c2ca233f-0cd8-4fae-8136-b40593792071",
+    "to": "d3db344g-0cd8-4fae-8136-b40593792071"


the character 'g' in the to field is not valid hexadecimal. Replace with a valid character (0-9, a-f).

greptile-apps · 2026-02-13T11:16:00Z

+```json Output
+{
+  "vector_node": {
+    "id": "a1b2c3d4-3fg1-7hij-1469-e73826025204",


characters 'g', 'h', 'i', 'j' in this ID are not valid hexadecimal (valid range: 0-9, a-f). Replace with valid hex characters.

greptile-apps · 2026-02-13T11:16:01Z

-    { "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" }


character 'g' in Bob's ID is not valid hexadecimal. Replace with a valid character (0-9, a-f).

greptile-apps · 2026-02-13T11:16:02Z

+    { "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" }
  ]


character 'h' in Charlie's ID is not valid hexadecimal. Replace with a valid character (0-9, a-f).

greptile-apps · 2026-02-13T11:16:03Z

+  "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!"},
+    ...


character 'g' in the post ID is not valid hexadecimal. Replace with a valid character (0-9, a-f).

greptile-apps · 2026-02-13T11:16:04Z

+    { "id": "d3db344g-1de9-5gbf-9247-c51604803082", "name": "Bob", "age": 30 },
+    { "id": "e4ec455h-2ef0-6hcg-0358-d62715914193", "name": "Charlie", "age": 28 }


IDs contain 'g' and 'h' which are not valid hexadecimal characters. Replace with valid characters (0-9, a-f).

mintlify bot deployed to staging February 13, 2026 11:12 View deployment

greptile-apps bot reviewed Feb 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document HelixQL response structure and add JSON output examples#47

Document HelixQL response structure and add JSON output examples#47
xav-db wants to merge 1 commit intomainfrom
claude/document-return-objects-RXi6v

xav-db commented Feb 13, 2026 •

edited by greptile-apps bot

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

greptile-apps bot Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		{ "id": "d3db344g-1de9-5gbf-9247-c51604803082", "name": "Bob", "age": 30 },
		{ "id": "e4ec455h-2ef0-6hcg-0358-d62715914193", "name": "Charlie", "age": 28 }

Conversation

xav-db commented Feb 13, 2026 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Notable Details

Greptile Overview

Greptile Summary

Important Files Changed

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

xav-db commented Feb 13, 2026 •

edited by greptile-apps bot

Loading