Skip to content

Latest commit

 

History

History
353 lines (296 loc) · 5.17 KB

WIP_QueryRedesign.md

File metadata and controls

353 lines (296 loc) · 5.17 KB

Requirements

There are query features that we want to have eventually. We might not be able to implement (or use) all of them right away.

It is our desire that current query language should be compatible with future improvements. This is not always possible because it's impossible to predict future use, but at least we want to avoid traps that are already known to not work in the future.

Below are requirements that we already know to exist:

JSON

For simplicity of early design, we want both requests and responses to be JSON

Filters

We need to be able to search for properties, e.g. "age is at least 20".

{
  "type": "Person"
  "age>=": 20,
}

More filters

We'll need also need more comparisons:

  • != (including null comparison)
  • == (including null comparison)
  • >=
  • <=
  • >
  • <

Response is structurally similar to request

We want the request to "look similar" to the response

Request Response 
{
  "age": 20,
  "friends": ???
}
 
{
  "type": "Person",
  "name": "Someone",
  "age": 20,
  "friends": [
    { "id": "friend1", /* ... */ },
    { "id": "friend2", /* ... */ },
  ],
}

Property encoding

Return dateCreated property in milliseconds (/seconds/hours/days/..)

dateCreated(unit: millisecond)

Independent edges

In pseudo-syntax:

{
  "id": "abcde",
  "[[oldFriends]]": {
    "name": "friend",
    "item": {
      "knownSince<": 1234567
    }
  },
  "[[bestFriends]]": {
    "name": "friend",
    "item": {
      "activity>=": 3
    }
  }
}

=>

{
  "id": "abcde",
  "[[oldFriends]]": [
    // ...
  ],
  "[[bestFriends]]": [
    // ...
  ]
}

Out of scope

Variables, Fragments etc are out of scope for now.

Solutions

This section is for the Work-In-Progress solution proposal. It's not final, but it should guide us on what to do right now.

Request all forward edges

The simplest request with edges, get all of them in a search request:

Request Response 
{
  "id": "abcde",
  "[[edges]]": {}
}
 
{
  "id": "abcde",
  "age": 20,
  "name": "Bob",
  "[[edges]]": [
    {
      "_edge": "friend", // edge name
      "order": 1000,
      "_item": {
        "id": "this_friend",
        "age": 15,
        // ...
      }
    },
    {
      "_edge": "friend",
      "order": 1001,
      "_item": {
        "id": "another_friend",
        "age": 30,
        // ...
      }
    },
    // ...
  ]
  // ...
}

Future: filter edges

In this example, get friends that are know to you since a specific DateTime ("old friends").

Request Response 
{
  "id": "abcde",
  "[[myOldFriends]]": {
    "_edge": "friend",
    "_item": {
      "knownSince>=": 12345,
      // ...
    }
  }
}
 
{
  "id": "abcde",
  "age": 20,
  "name": "Bob",
  "[[myOldFriends]]": [
    // ... all friends with knownSince property of at least 12345
  ]
  // ...
}

Syntactic sugar

During our discussions on Schema design it was hypothesized that many people would be interested in simple access to edges. This means no filtering on edge properties, and expecting responses that have edges without any properties in them. (As opposed to, for example, Machine Learning predictions that would have edge properties, have edges pointing to other edges, have edge labels, etc etc.)

It is thus important to make the simple use case -- simple. Solution proposal:

Request Response 
{
  "id": "abcde",
  "[friend]": {
    "knownSince>=": 12345
  }
}
 
{
  "id": "abcde",
  "age": 20,
  "name": "Bob",
  "[friend]": [
    { "id": "friend1", "knownSince": 12388, /* ... */ },
    { "id": "friend2", "knownSince":  12399, /* ... */ },
    // ... Note that the intermediate edge
    // and its properties are missing in both
    // the request and the response.
  ]
}

(?) All forward and backward edges simultaneously:

Request Response 
{
  "id": "abcde",
  "[[edges]]": {},
  "~[[edges]]": {},
}
 
{
  "id": "abcde",
  "name": "Bob",
  "[[edges]]": [
    { "_edge": "father", "_item": { /* ... */ } },
    { "_edge": "friend", "_item": { /* ... */ } },
    { "_edge": "friend", "_item": { /* ... */ } },
  ],
  "~[[edges]]": [
    { "_edge": "child", "_item": { /* ... */ } },
  ],
  // ...
}

(?) All reverse edges without edge properties:

Request Response 
{
  "id": "abcde",
  "~[*]": {}
}
 
{
  "id": "abcde",
  "name": "Bob",
  "~[friend]": [
    { "id": "friend1", /* ... */ },
    { "id": "friend2", /* ... */ },
  ],
  "~[child]": [
    { "id": "father", /* ... */ },
  ],
  // ...
}

(Not finalized, might change)

Support for today

To see what is already supported by the current version of Pod, see HTTP_API.