Skip to content

Add Map and Point types to result set structure documentation #396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add Map and Point types to result set structure documentation #396

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c42dc37
Initial plan
Copilot Mar 21, 2026
6613f91
Add map and point types to result set structure and client spec docs
Copilot Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions design/client-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,31 @@ As such, the complete representation is as follows:

The `ValueType` for the third entry is `VALUE_STRING`, and the other element in the array is the actual value, "Apple".

#### Maps (VALUE_MAP = 10)

A map is emitted as a flat array of key-value pairs, where each key is a string and each value is a 2-array of [`ValueType`, value]. For example, the map `{name: 'John', age: 30}` is serialized as:

```sh
[
key (string), [ValueType (enum), value (scalar)],
key (string), [ValueType (enum), value (scalar)],
...
Comment on lines +234 to +236
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the Maps serialization pseudo-structure, the value placeholder is labeled as value (scalar), but map values can be non-scalar (e.g., arrays, nodes/edges, paths, nested maps, points). This can mislead client authors into rejecting valid responses. Consider changing the placeholder to something like value (any ValueType payload) or explicitly stating that the value can be any FalkorDB value type, not just scalars.

Copilot uses AI. Check for mistakes.
]
```

The total array length is `2 * key_count` (one entry for the key string, one entry for the typed value).

#### Points (VALUE_POINT = 11)

A point is emitted as a 2-array containing the latitude and longitude as double-precision floating-point values:

```sh
[
latitude (double),
longitude (double)
]
```

### Reading statistics

The final top-level member of the GRAPH.QUERY reply is the execution statistics. This element is identical between the compact and standard response formats.
Expand Down
39 changes: 32 additions & 7 deletions design/result-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,14 @@ A column in the result set can be populated with graph entities (nodes or relati

FalkorDB replies are formatted using the [RESP protocol](https://redis.io/topics/protocol). The current RESP iteration provides fewer data types than FalkorDB supports internally, so displayed results are mapped as follows:

| FalkorDB type | Display format |
|-----------------|-----------------------------|
| Integer | Integer |
| NULL | NULL (nil) |
| String | String |
| Boolean | String ("true"/"false") |
| Double | String (15-digit precision) |
| FalkorDB type | Display format |
|---------------|-----------------------------------------------------|
| Integer | Integer |
| NULL | NULL (nil) |
| String | String |
| Boolean | String ("true"/"false") |
| Double | String (15-digit precision) |
| Point | String ("point({latitude:%f, longitude:%f})") |

### Graph Entities

Expand Down Expand Up @@ -95,6 +96,30 @@ The string representation of an array which contains graph entities, will print

Returned path value is the string representation of an array with the path's nodes and edges, interleaved.

#### Maps

When a map value is returned, the verbose representation is the string representation of the map's key-value pairs. For example:

```sh
"RETURN {name: 'John', age: 30} AS map"
1) 1) "map"
2) 1) 1) "{name: John, age: 30}"
3) 1) "Query internal execution time: 0.5 milliseconds"
```

Maps cannot be stored as property values.

#### Points

When a point value is returned, the verbose representation is a string in the format `point({latitude:<lat>, longitude:<lon>})`. For example:

```sh
"RETURN point({latitude: 51.5074, longitude: -0.1278}) AS p"
1) 1) "p"
2) 1) 1) "point({latitude:51.507400, longitude:-0.127800})"
3) 1) "Query internal execution time: 0.5 milliseconds"
```

## Example

Given the graph created by the command:
Expand Down
Loading