Values and Types

UQL 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-[m]m-[d]d 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

Temporal Duration

Boolean

Spatial

Record

Binary

List and Set

Constructed Value Types

A constructed value type is a data type comprising composite elements. UQL supports the following constructed type:

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 the information of @Paper nodes:

UQL
find().nodes({@Paper}) as n
return n{*}

Data structure of n:

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 the information of outgoing @Cites edges:

UQL
n().re({@Cites} as e).n()
return e{*}

Data structure of e:

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 the information of outgoing 1-step paths:

UQL
n().re().n() as p
return p{*}

Data structure of p:

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 @Paper nodes:

UQL
find().nodes({@Paper}) as n
return n.title

Data structure of n.title:

table
{
  "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:

UQL
find().nodes({@Paper}) as n
return table(n.title, n.score) as table

Data structure of table:

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 schema, any existing nodes or edges with that schema 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 statements like find() and khop(), if no result is found, the clause yields null instead of empty return.

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.