> ## Documentation Index
> Fetch the complete documentation index at: https://helix-claude-document-return-objects-rxi6v.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Output Values
> What you can return from a query using RETURN.
HelixQL queries end with a `RETURN` clause. You can return bindings (variables),
projected properties, aggregations, literals, or choose to return nothing at all.
## Quick reference
| Return Type | Syntax | Return Type | Syntax |
| ---------------- | ------------------------------- | ------------------ | -------------------------- |
| Return a binding | `RETURN users` | Exclude fields | `RETURN users::!{ email }` |
| Return multiple | `RETURN user, posts` | Aggregation/scalar | `RETURN count` |
| Project fields | `RETURN users::{ name, age }` | Literal | `RETURN "ok"` |
| Only IDs | `RETURN users::ID` | No payload | `RETURN NONE` |
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 theme={null}
{ "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 theme={null}
{ "id": "a1b2c3d4-...", "from": "c2ca233f-...", "to": "d3db344g-...", "since": "2024-01-15" }
```
**Vector** — includes metadata properties defined in the schema.
```json theme={null}
{ "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.
```helixql Query theme={null}
QUERY GetAllUsers() =>
users <- N
RETURN users
```
```helixql Schema theme={null}
N::User {
name: String,
age: U8,
email: String
}
```
```json Output theme={null}
{
"users": [
{ "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" }
]
}
```
Returning multiple values creates multiple top-level fields in the response, named
after the variables.
```helixql Query theme={null}
QUERY GetUserAndPosts(user_id: ID) =>
user <- N(user_id)
posts <- user::Out
RETURN user, posts
```
```helixql Schema [expandable] theme={null}
N::User {
name: String,
age: U8,
email: String
}
N::Post {
title: String,
content: String
}
E::User_to_Post {
From: User,
To: Post
}
```
```json Output theme={null}
{
"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!"},
...
]
}
```
***
## Returning projections and properties
Use property projection to shape the returned data.
```helixql Query theme={null}
QUERY FindUsers() =>
users <- N::RANGE(0, 10)
RETURN users::{ name, age }
```
```helixql Schema theme={null}
N::User {
name: String,
age: U8,
email: String
}
```
```json Output theme={null}
{
"users": [
{ "name": "Alice", "age": 25 },
{ "name": "Bob", "age": 30 },
{ "name": "Charlie", "age": 28 }
]
}
```
Return just the `ID` of each element:
```helixql Query theme={null}
QUERY FindUserIDs() =>
users <- N::RANGE(0, 10)
RETURN users::ID
```
```helixql Schema theme={null}
N::User {
name: String,
age: U8,
email: String
}
```
```json Output theme={null}
{
"users": [
"c2ca233f-0cd8-4fae-8136-b40593792071",
"d3db344g-1de9-5gbf-9247-c51604803082",
"e4ec455h-2ef0-6hcg-0358-d62715914193"
]
}
```
Exclude specific properties:
```helixql Query theme={null}
QUERY FindUsersNoPII() =>
users <- N::RANGE(0, 10)
RETURN users::!{ email, location }
```
```helixql Schema theme={null}
N::User {
name: String,
age: U8,
email: String,
location: String
}
```
```json Output theme={null}
{
"users": [
{ "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 }
]
}
```
You can also create nested or remapped shapes in `RETURN` using nested mappings:
```helixql Query theme={null}
QUERY FindFriends(user_id: ID) =>
user <- N(user_id)
posts <- user::Out::RANGE(0, 20)
RETURN user::|u|{
userID: u::ID,
posts: posts::{
postID: ID,
creatorID: u::ID,
..
}
}
```
```helixql Schema [expandable] theme={null}
N::User {
name: String,
age: U8,
email: String
}
N::Post {
title: String,
content: String
}
E::User_to_Post {
From: User,
To: Post
}
```
```json Output theme={null}
{
"user": {
"userID": "c2ca233f-0cd8-4fae-8136-b40593792071",
"posts": [
{
"postID": "d3db344g-1de9-5gbf-9247-c51604803082",
"creatorID": "c2ca233f-0cd8-4fae-8136-b40593792071",
"title": "My First Post",
"content": "This is my first blog post!"
},
{
"postID": "e4ec455h-2ef0-6hcg-0358-d62715914193",
"creatorID": "c2ca233f-0cd8-4fae-8136-b40593792071",
"title": "Weekend Plans",
"content": "Planning to explore the city."
}
]
}
}
```
See [property access](../hql/properties/property-access), [remappings](../hql/properties/property-remappings), and [exclusion](../hql/properties/property-exclusion) for more details.
***
## Returning scalars and literals
Aggregations and scalar bindings can be returned directly:
```helixql Query theme={null}
QUERY CountUsers() =>
user_count <- N::COUNT
RETURN user_count
```
```helixql Schema theme={null}
N::User {
name: String,
age: U8,
email: String
}
```
```json Output theme={null}
{
"user_count": 42
}
```
You can also return literals (strings, numbers, booleans) when useful:
```helixql Query theme={null}
QUERY DeleteCity(city_id: ID) =>
DROP N(city_id)
RETURN "success"
```
```helixql Schema theme={null}
N::City {
name: String,
population: U32
}
```
```json Output theme={null}
{
"result": "success"
}
```
***
## Returning nothing
For mutations or maintenance operations where you do not want a response payload,
use `RETURN NONE`.
```helixql Query theme={null}
QUERY DeleteCityQuietly(city_id: ID) =>
DROP N(city_id)
RETURN NONE
```
```helixql Schema theme={null}
N::City {
name: String,
population: U32
}
```
```json Output theme={null}
{}
```
`RETURN NONE` signals that the query intentionally produces no output values. This is
handy to avoid sending placeholder strings like "success" when a silent acknowledgement
is preferred.