apache / apache/druid

Proposal to add new resultFormat - to wrap the Druid SQL JSON result array in a JSON object.

Open
#8,816 2 comments 0 reactions 0 assignees View on GitHub
Area - Querying Feature/Change Description Starter
Dominant language
Java
Stars
14.1k
Forks
3.8k
Avg merge
2d 58m
Merged PRs (30d)
233

Description

### Description

As of `0.16.0`, Druid SQL queries made using JSON over HTTP to the Druid broker would by default return a JSON array of JSON objects (with `"resultFormat": "object"`).

This is an alternative `resultFormat` proposal which is similar to the default `object`, but returns a JSON object wrapping the JSON result array.

### Motivation
Two primary reasons for this proposal:
- This would keep the successful response consistent with the error response, also containing a JSON object as shown [here](https://druid.apache.org/docs/latest/querying/querying.html#query-errors).
- In addition, some serialization formats like JSON<->protobuf today don't support (un)marshaling a top-level JSON array, so a JSON object would be preferred (instead of manually concatenating the JSON array results) - more details can be found [here](https://github.com/golang/protobuf/issues/675#issuecomment-411182202).

The new `resultFormat` will be a JSON object containing a key, for example `"data"`, and then have the resulting JSON array as the value. This is similar to the [“error”](https://druid.apache.org/docs/latest/querying/querying.html#query-errors) response case, where we have `"error"`, `"errorMessage"`, etc., as the keys in the response object.

**Example of current behavior**:
```json
[
{
"page": "Wikipedia:Vandalismusmeldung",
"Edits": 33
},
{
"page": "User:Cyde/List of candidates for speedy deletion/Subpage",
"Edits": 28
},
{
"page": "Jeremy Corbyn",
"Edits": 27
}
]
```
**Proposal format**:
```json
{
"data": [
{
"page": "Wikipedia:Vandalismusmeldung",
"Edits": 33
},
{
"page": "User:Cyde/List of candidates for speedy deletion/Subpage",
"Edits": 28
},
{
"page": "Jeremy Corbyn",
"Edits": 27
}
]
}
```

Contributor guide

Open the contributing guide

Research direction

Start with Druid SQL JSON-over-HTTP responses from the broker and the existing resultFormat "object" behavior; the issue names no files or tests. Review the query-errors response contract and determine the wrapper key, compatibility expectations, implementation scope, and documentation needed before considering the proposal complete.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.