Values and Types

GQL supports various values and types to represent data within the graph database. Understanding these values and types is essential for effective query construction and data manipulation.

Graph Element Types

Graph element types consist of node types and edge types, which are the data types of nodes and edges respectively.

Property Value Types

A property value type refers to the data type of the values of a property. Ultipa supports the following property value types:

Constructed Value Types

A constructed value type is a data type comprising composite elements. GQL defines the following constructed value types:

^[1] If the ordered sequence of nodes and edges in a path element list forms a path, then the sequence is said to identify a path.

Result Types

A result type refers to the data type of the values returned by a query. Ultipa defines the following result types.

RESULT_TYPE_NODE

This query returns all nodes labeled Paper bound to the variable n:

MATCH (n:Paper) RETURN n

Data structure of n:

{
  "data": [
    {
      "id": "P2",
      "uuid": "8718971077612535835",
      "schema": "Paper",
      "values": {
        "title": "Optimizing Queries",
        "score": 9
      }
    },
    {
      "id": "P1",
      "uuid": "8791028671650463770",
      "schema": "Paper",
      "values": {
        "title": "Efficient Graph Search",
        "score": 6
      }
    }
  ],
  "alias": "n",
  "type": 2,
  "type_desc": "RESULT_TYPE_NODE"
}

RESULT_TYPE_EDGE

This query returns all outgoing edges labeled Cites bound to the variable e:

MATCH ()-[e:Cites]->() RETURN e

Data structure of e:

{
  "data": [
    {
      "from": "P1",
      "to": "P2",
      "uuid": "1",
      "from_uuid": "8791028671650463770",
      "to_uuid": "8718971077612535835",
      "schema": "Cites",
      "values": {
        "weight": 2
      }
    }
  ],
  "alias": "e",
  "type": 3,
  "type_desc": "RESULT_TYPE_EDGE"
}

RESULT_TYPE_PATH

This query returns all outgoing 1-step paths bound to the variable p:

MATCH p = ()-[]->() RETURN p

Data structure of p:

{
  "data": [
    {
      "nodes": [
        {
          "id": "P1",
          "uuid": "8791028671650463770",
          "schema": "Paper",
          "values": {
            "title": "Efficient Graph Search",
            "score": 6
          }
        },
        {
          "id": "P2",
          "uuid": "8718971077612535835",
          "schema": "Paper",
          "values": {
            "title": "Optimizing Queries",
            "score": 9
          }
        }
      ],
      "edges": [
        {
          "from": "P1",
          "to": "P2",
          "uuid": "1",
          "from_uuid": "8791028671650463770",
          "to_uuid": "8718971077612535835",
          "schema": "Cites",
          "values": {
            "weight": 2
          }
        }
      ],
      "length": 1
    }
  ],
  "alias": "p",
  "type": 1,
  "type_desc": "RESULT_TYPE_PATH"
}

RESULT_TYPE_ATTR

This query returns the title property of nodes labeled Paper:

MATCH (n:Paper) RETURN n.title

Data structure of n.title:

{
  "data": {
    "alias": "n.title",
    "type": 4,
    "type_desc": "RESULT_TYPE_ATTR",
    "values": [
      "Optimizing Queries",
      "Efficient Graph Search"
    ]
  },
  "alias": "n.title",
  "type": 4,
  "type_desc": "RESULT_TYPE_ATTR"
}

RESULT_TYPE_TABLE

This query returns a table bound to the variable table:

MATCH (n:Paper) RETURN table(n.title, n.score) AS table

Data structure of table:

{
  "data": {
    "name": "table",
    "alias": "table",
    "headers": [
      "n.title",
      "n.score"
    ],
    "rows": [
      [
        "Optimizing Queries",
        "9"
      ],
      [
        "Efficient Graph Search",
        "6"
      ]
    ]
  },
  "alias": "table",
  "type": 5,
  "type_desc": "RESULT_TYPE_TABLE"
}

Null Value

The null value is a special value available in all nullable types. Any non-null value is a material value.

Null Scenarios

The null values can arise in various contexts, including:

• Default Assignment: When nodes or edges are inserted, nullable properties that lack specified values automatically receive null.
• Explicit Null Specification: During node or edge insertion, nullable properties can be intentionally set to null.
• Value Removal: Removing a property’s value sets it to null.
• New Property Assignment: When adding a new property to a label, any existing nodes or edges with that label are assigned null for the new property by default.
• Nonexistent Property References: Referencing a property that does not exist returns null.
• Optional Matching: When the OPTIONAL keyword is used with the MATCH statement, if no result is found for the pattern, MATCH yields null instead of empty return.
• NULLIF Expression: The NULLIF expression returns null if the two compared values are equal.

Null in Comparisons

The null value is not comparable to any other value due to its inherently unknown nature. Consequently, comparisons involving null using normal operators such as = or <> do not typically yield true or false but rather an unknown result, also represented by null.

Comparisons involving null require special handling with null predicates (IS NULL and IS NOT NULL).

Null Treatments

The null values receive special treatment in some contexts. For instance:

• Aggregate functions typically ignore null values.
• The GROUP BY clause groups all null values together.
• The ORDER BY statement allows for null ordering using the NULLS FIRST and NULL LAST keywords.