Update the HTTP-TS driver with analyze endpoint response #783
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
krishnangovindraj
requested review from
alexjpwalker,
flyingsilverfin and
sam-butcher
krishnangovindraj
changed the title
http-ts/src/analyze.ts
Outdated
| { tag: "reduce", reducers: Reducer[] } | ||
|
|
||
| export type VariableAnnotations = | ||
| { tag: "concept", annotations: Type[] } | |
Member
There was a problem hiding this comment.
Change to thing and type separately
http-ts/src/analyze.ts
Outdated
|
|
||
| export interface FunctionAnnotations { | ||
| arguments: VariableAnnotations[], | ||
| returned: VariableAnnotations[], |
Member
There was a problem hiding this comment.
returns : {
tag: "single" | "stream",
annotations: VariableAnnotations[],
}
flyingsilverfin
approved these changes
Sep 2, 2025
krishnangovindraj
added a commit
to typedb/typedb
that referenced
this pull request
Sep 3, 2025
## Product change and motivation
We revise the response format for the `analyze` endpoint of the HTTP API, to align it better with TypeDB's representation, and simplify parsing & reconstructing the structure.
Major changes include:
* `Or`, `Not` and `Try` blocks are now included in the block constraints. Hence the conjunction tree structure is represented within the blocks. This avoids a relatively convoluted interplay between `pipeline.structure.conjunctions` and `pipeline.structure.blocks` in reconstructing the conjunction tree.
* A `match` stage under a `pipeline` structure now only needs to hold a single `blockId` instead of a tree representing the conjunction.
* Fetch annotations are more structured, for easier parsing in all languages. Previously, the dynamic keys required a map with a union of values to parse properly. Now it's simply a union of static types, and provides the user a schema for the returned JSON object.
```
export type FetchAnnotations =
{ tag: "list", elements: FetchAnnotations } |
{ tag : "object", possibleFields: FetchAnnotationFieldEntry[] } |
{ tag : "value", valueTypes: ValueType[] };
export type FetchAnnotationFieldEntry = FetchAnnotations & { key: string };
```
For a more complete spec, see typedb/typedb-driver#783
## Implementation
## Sample output
```
with fun title($book: book) -> string:
match $book has title $title;
let $as_string = $title;
return first $as_string;
match
$book isa book;
fetch {
"title": title($book),
"title_list" : [$book.title]
};
```
```json
{
"structure": {
"query": {
"conjunctions": [
[
{
"textSpan": { "begin": 131, "end": 139 },
"tag": "isa",
"instance": { "tag": "variable", "id": "0" },
"type": {
"tag": "label",
"type": { "kind": "entityType", "label": "book" }
}
}
]
],
"pipeline": [
{ "tag": "match", "block": 0 }
],
"variables": {
"0": { "name": "book" }
},
"outputs": [ "0" ]
},
"preamble": [
{
"body": {
"conjunctions": [
[
{
"textSpan": { "begin": 51, "end": 67 },
"tag": "has",
"owner": { "tag": "variable", "id": "0" },
"attribute": { "tag": "variable", "id": "1" }
},
{
"textSpan": { "begin": 55, "end": 60 },
"tag": "isa",
"instance": { "tag": "variable", "id": "1" },
"type": {
"tag": "label",
"type": { "kind": "attributeType", "label": "title", "valueType": "string" }
}
},
{
"textSpan": { "begin": 69, "end": 92 },
"tag": "expression",
"text": "let $as_string = $title",
"assigned": [
{ "tag": "variable", "id": "2" }
],
"arguments": [
{ "tag": "variable", "id": "1" }
]
}
]
],
"pipeline": [
{ "tag": "match", "block": 0 }
],
"variables": {
"0": { "name": "book" },
"1": { "name": "title" },
"2": { "name": "as_string" }
},
"outputs": [ "2" ]
},
"arguments": [ "0" ],
"returns": {
"tag": "single",
"selector": "first",
"variables": [ "2" ]
}
}
]
},
"annotations": {
"preamble": [
{
"arguments": [
{
"tag": "thing",
"annotations": [
{ "kind": "entityType", "label": "hardback" },
{ "kind": "entityType", "label": "paperback" },
{ "kind": "entityType", "label": "ebook" }
]
}
],
"returns": {
"tag": "single",
"annotations": [
{
"tag": "value",
"valueTypes": [ "string" ]
}
]
},
"body": {
"annotationsByConjunction": [
{
"variableAnnotations": {
"0": {
"tag": "thing",
"annotations": [
{ "kind": "entityType", "label": "hardback" },
{ "kind": "entityType", "label": "paperback" },
{ "kind": "entityType", "label": "ebook" }
]
},
"1": {
"tag": "thing",
"annotations": [
{ "kind": "attributeType", "label": "title", "valueType": "string" }
]
}
}
}
]
}
}
],
"query": {
"annotationsByConjunction": [
{
"variableAnnotations": {
"0": {
"tag": "thing",
"annotations": [
{ "kind": "entityType", "label": "hardback" },
{ "kind": "entityType", "label": "paperback" },
{ "kind": "entityType", "label": "ebook" }
]
}
}
}
]
},
"fetch": {
"tag": "object",
"possibleFields": [
{
"key": "title_list",
"tag": "list",
"elements": {
"tag": "value",
"valueTypes": [ "string" ]
}
},
{
"key": "title",
"tag": "value",
"valueTypes": [ "string" ]
}
]
}
}
}
```
** - - - - **
```
match $x isa $t; not { { $t owns $s; } or { $t plays $_; }; };
```
```json
{
"structure": {
"query": {
"conjunctions": [
[
{
"textSpan": { "begin": 28, "end": 35 },
"tag": "owns",
"owner": { "tag": "variable", "id": "1" },
"attribute": { "tag": "variable", "id": "2" }
}
],
[
{
"textSpan": { "begin": 47, "end": 55 },
"tag": "plays",
"player": { "tag": "variable", "id": "1" },
"role": { "tag": "variable", "id": "3" }
}
],
[
{
"textSpan": null,
"tag": "or",
"branches": [ 0, 1 ]
}
],
[
{
"textSpan": { "begin": 9, "end": 15 },
"tag": "isa",
"instance": { "tag": "variable", "id": "0" },
"type": { "tag": "variable", "id": "1" }
},
{ "textSpan": null, "tag": "not", "conjunction": 2 }
]
],
"pipeline": [
{ "tag": "match", "block": 3 }
],
"variables": {
"2": { "name": "s" },
"1": { "name": "t" },
"0": { "name": "x" },
"3": { "name": null }
},
"outputs": [ "0", "1", "2" ]
},
"preamble": []
},
"annotations": {
"preamble": [],
"query": {
"annotationsByConjunction": [
{
"variableAnnotations": {
"1": {
"tag": "type",
"annotations": [...],
},
"2": {
"tag": "type",
"annotations": [...],
}
}
},
{
"variableAnnotations": {
"3": {
"tag": "type",
"annotations": [...],
},
"1": {
"tag": "type",
"annotations": [...],
}
}
},
{
"variableAnnotations": {
"1": {
"tag": "type",
"annotations": [...],
}
}
},
{
"variableAnnotations": {
"0": {
"tag": "thing",
"annotations": [...],
},
"1": {
"tag": "type",
"annotations": [...],
}
}
}
]
},
"fetch": null
}
}
```
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Usage and product changes
Update the HTTP-TS driver with the response structure for the analyze endpoint