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. In a closed graph, property types are explicitly defined when creating node/edge types. The following types are available:

Numeric

Textual

Temporal Instant

Date Formats

• 2025-01-05 or 2025-1-5
• 2025/01/05 or 2025/1/5
• 20250105

Time Formats

• 12:20:02.55254 (with fractional seconds up to 9 digits)
• 12:20:02
• 12:20 (without seconds)
• 122002 or 122002.55254

Date-Time Formats

The date and time parts are joined by either a space or the letter T:

• 2025-01-05 12:20:02
• 2025-01-05T12:20:02

Timezone Formats

For ZONED DATETIME and ZONED TIME, timezone is specified as an RFC 3339 UTC offset:

• +08:00, -05:30
• Z (UTC)

DATETIME Additional Formats

DATETIME accepts all the above date-time formats, plus:

• 25-1-1 12:20:2 (two-digit year)
• 2025-01-01 (time part omitted, defaults to 00:00:00)

Temporal Duration

Boolean

Spatial

Binary

Record

List

Vector

Open Graph Property Types

In an open graph, property types are not explicitly defined. Instead, the type is inferred from the literal value at insertion time. The following types are used:

The same property name on different nodes can have different types. There is no fine-grained type control (e.g., UINT32 vs INT64 — all integers are stored as INT).

NOTE

Unlike closed graphs where string values are auto-converted to the defined property type (e.g., '2025-01-05' is auto-parsed as DATE), open graphs store string values as STRING. To create temporal, spatial, or vector values in an open graph, use constructor functions such as date('2025-01-05'), local_datetime('2025-01-01 12:00:00'), duration('P2Y5M'), point(125.6, 22.3), ai.vector(\[0.1, 0.2]), etc.

Query Response

Query results are returned as a list of rows, where each row is a map of column names to typed values.

GQL
MATCH (n:User) RETURN n, n.name LIMIT 2

JSON
[
  {
    "n": {
      "id": "U1",
      "labels": ["User", "Employee"],
      "properties": {"name": "Quasar92"}
    },
    "n.name": "Quasar92"
  },
  {
    "n": {
      "id": "5944db0b-aa82-419c-bdd6-d332f0372b89",
      "labels": ["User"],
      "properties": {"name": "claire", "gender": "female"}
    },
    "n.name": "claire"
  }
]

Each cell value has one of the following types:

Driver libraries provide convenience methods to extract typed objects from the response. See the Driver Documentation for details.

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: In a closed graph, when nodes or edges are inserted, properties not explicitly provided default to null (unless a NOT NULL constraint is defined).
• Explicit Null Specification: During node or edge insertion, nullable properties can be intentionally set to null.
• Value Removal: Using REMOVE on a property sets its value to null in a closed graph. In an open graph, the property is removed from the node or edge.
• New Property Assignment: In a closed graph, when adding a new property to a type, any existing nodes or edges of that type 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 NULLS LAST keywords.