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.

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:

Numeric

Textual

Temporal Instant

Date

• Format: yyyy-mm-dd or yyyymmdd
• Range: -9999-12-31 to 9999-12-31

Time

• Format: hh:mm:ss[.fraction] or hhmmss[.fraction]
• Range: 00:00:00.000000000 to 23:59:59.999999999

Date and Time

• Format: The date and time parts are joined by either a space or the letter T.
• Range: -9999-01-01 00:00:00.000000000 to 9999-12-31 23:59:59.999999999

Timezone

• Format: Represented as a UTC offset in the form of ±hh:mm or ±hhmm, appended directly to the time value.
• Range: UTC-15:00 to UTC+15:00

Except for timestamps, all temporal instant types must be enclosed in quotes when assigned.

Temporal Duration

Boolean

Spatial

List

Constructed Value Types

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

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.