Data Types

The GQLDB Go driver supports a comprehensive set of data types for storing and querying graph data. This guide covers property types, enums, and type conversions.

Property Types

The PropertyType constants define all supported data types:

Go
import gqldb "github.com/ultipa/ultipa-go-driver/v6"

Numeric Types

String Types

Boolean and Null

Binary

Date and Time Types

Duration Types

Geospatial Types

Collection Types

Graph Types

PropertyType Constants

Go
const (
    PropertyTypeUnset
    PropertyTypeInt32
    PropertyTypeUint32
    PropertyTypeInt64
    PropertyTypeUint64
    PropertyTypeFloat
    PropertyTypeDouble
    PropertyTypeString
    PropertyTypeDatetime      // Deprecated, use PropertyTypeTimestamp
    PropertyTypeTimestamp
    PropertyTypeText
    PropertyTypeBlob
    PropertyTypePoint
    PropertyTypeDecimal
    PropertyTypeList
    PropertyTypeSet
    PropertyTypeMap
    PropertyTypeNull
    PropertyTypeBool
    PropertyTypeLocalDatetime
    PropertyTypeZonedDatetime
    PropertyTypeDate
    PropertyTypeZonedTime
    PropertyTypeLocalTime
    PropertyTypeYearToMonth
    PropertyTypeDayToSecond
    PropertyTypeRecord
    PropertyTypePoint3D
    PropertyTypeVector
    PropertyTypeTable
    PropertyTypePath
    PropertyTypeError
    PropertyTypeNode
    PropertyTypeEdge
)

GraphType Constants

Go
const (
    GraphTypeOpen     // Schema-less graph
    GraphTypeClosed   // Schema-enforced graph
    GraphTypeOntology // Ontology-enabled graph
)

HealthStatus Constants

Go
const (
    HealthStatusUnknown
    HealthStatusServing
    HealthStatusNotServing
    HealthStatusServiceUnknown
)

CacheType Constants

Go
const (
    CacheTypeAll
    CacheTypeAST
    CacheTypePlan
)

InsertType Constants

Controls the GQL keyword emitted by InsertNodesGql / InsertEdgesGql, and the duplicate-_id semantic for InsertNodes / InsertEdges (via InsertNodesConfig.Mode / InsertEdgesConfig.Mode):

Go
type InsertType int

const (
    InsertTypeNormal    InsertType = 0  // INSERT — errors on duplicate _id
    InsertTypeOverwrite InsertType = 1  // INSERT OVERWRITE — replaces entity wholesale
    InsertTypeUpsert    InsertType = 2  // UPSERT — merges new properties into existing entity
)

InsertTypeOverwrite drops properties not present in the write. InsertTypeUpsert preserves them and only overwrites the ones present in the write. They are not interchangeable.

InsertConfig

Per-call configuration for the GQL-emitter convenience helpers (InsertNodesGql / InsertEdgesGql). Embeds QueryConfig:

Go
type InsertConfig struct {
    QueryConfig                     // embedded — GraphName, Timeout, TransactionID, etc.
    InsertType InsertType           // defaults to InsertTypeNormal (zero value)
}

Pass nil to use the session graph and InsertTypeNormal.

InsertNodesConfig / InsertEdgesConfig

Configuration for the gRPC bulk-import functions (InsertNodes / InsertEdges):

Go
type InsertNodesConfig struct {
    Mode                InsertType   // Normal / Overwrite / Upsert
    BulkImportSessionID string       // Optional: bulk import session ID for auto-checkpoint
}

type InsertEdgesConfig struct {
    SkipInvalidNodes    bool         // Skip edges where source/target node doesn't exist
    Mode                InsertType   // Normal / Overwrite / Upsert
    BulkImportSessionID string       // Optional: bulk import session ID for auto-checkpoint
}

Edge InsertTypeOverwrite and InsertTypeUpsert require WITH EDGE_ID on the target graph.

Type Structs

Node Types

Go
// Data for inserting nodes (input to InsertNodes / InsertNodesGql)
type NodeData struct {
    ID         string                  // Optional custom _id (auto-generated when empty)
    Labels     []string
    Properties map[string]interface{}
}

// Node from query results
type Node struct {
    ID         string                  // user-facing identifier
    UUID       string                  // system numeric handle, decimal-formatted;
                                       // empty on pre-6.1.147 servers
    Labels     []string
    Properties map[string]interface{}
}

Edge Types

Go
// Data for inserting edges (input to InsertEdges / InsertEdgesGql)
type EdgeData struct {
    ID         string                  // Optional custom _id; requires WITH EDGE_ID graph
    Label      string
    FromNodeID string
    ToNodeID   string
    Properties map[string]interface{}
}

// Edge from query results
type Edge struct {
    ID         string
    UUID       string                  // system numeric handle; empty on pre-6.1.147 servers
    Label      string
    FromNodeID string
    ToNodeID   string
    Properties map[string]interface{}
}

Path Type

Go
type Path struct {
    Nodes []*Node
    Edges []*Edge
}

Geospatial Types

Go
type Point struct {
    Latitude  float64
    Longitude float64
}

func (p Point) X() float64           // alias for Longitude
func (p Point) Y() float64           // alias for Latitude

type Point3D struct {
    X float64
    Y float64
    Z float64
}

func (p Point3D) Longitude() float64  // alias for X
func (p Point3D) Latitude() float64   // alias for Y
func (p Point3D) Height() float64     // alias for Z

Point validates against WGS-84 bounds server-side (longitude ∈ [-180, 180], latitude ∈ [-90, 90]). Point3D is Cartesian — the server does not enforce geographic bounds on Point3D, even when accessed through the lon/lat aliases.

Duration Types

Go
type YearToMonth struct {
    Months int32
}

type DayToSecond struct {
    Seconds     int64    // signed — negative durations (e.g. -PT1H) round-trip correctly
    Nanoseconds uint32
}

Vector Type

Go
type Vector struct {
    Values []float32
}

func (v Vector) Len() int            // dimension count

v.Len() returns the number of dimensions — mirrors the Python driver's len(vec) ergonomic and the server-side size(VECTOR) / ai.vector_dim(VECTOR) functions.

TypedValue

The driver uses TypedValue internally for type-safe data transfer:

Go
type TypedValue struct {
    Type   PropertyType
    Data   []byte
    IsNull bool
}

// Convert to Go type
func (tv *TypedValue) ToGo() (interface{}, error)

Creating TypedValues

Go
// Create from Go value
tv, err := gqldb.NewTypedValue(42)
tv, err = gqldb.NewTypedValue("hello")
tv, err = gqldb.NewTypedValue(3.14)
tv, err = gqldb.NewTypedValue(true)

Creating Parameters

Go
// Create query parameter
param, err := gqldb.NewParameter("name", "Alice")
param, err = gqldb.NewParameter("age", 30)

Type Conversion Examples

Working with Dates

Go
// Insert with date
client.Gql(ctx, `
    INSERT (e:Event {
        _id: 'e1',
        name: 'Conference',
        date: DATE('2024-06-15'),
        startTime: DATETIME('2024-06-15T09:00:00Z')
    })
`, nil)

// Query and convert
response, _ := client.Gql(ctx, "MATCH (e:Event) RETURN e.date, e.startTime", nil)
row := response.First()
if row != nil {
    date, _ := row.Get(0)
    startTime, _ := row.Get(1)
    fmt.Printf("Event date: %v\n", date)
    fmt.Printf("Start time: %v\n", startTime)
}

Working with Points

Go
// Insert with location
client.Gql(ctx, `
    INSERT (p:Place {
        _id: 'p1',
        name: 'Office',
        location: POINT(37.7749, -122.4194)
    })
`, nil)

// Query and access point
response, _ := client.Gql(ctx, "MATCH (p:Place) RETURN p.location", nil)
row := response.First()
if row != nil {
    location, _ := row.Get(0)
    if pt, ok := location.(*gqldb.Point); ok {
        fmt.Printf("Lat: %f, Lng: %f\n", pt.Latitude, pt.Longitude)
    }
}

Working with Collections

Go
// Insert with list and map
client.Gql(ctx, `
    INSERT (u:User {
        _id: 'u1',
        name: 'Alice',
        tags: ['developer', 'blogger'],
        metadata: {level: 5, premium: true}
    })
`, nil)

// Query collections
response, _ := client.Gql(ctx, "MATCH (u:User) RETURN u.tags, u.metadata", nil)
row := response.First()
if row != nil {
    tags, _ := row.Get(0)
    metadata, _ := row.Get(1)
    fmt.Printf("Tags: %v\n", tags)
    fmt.Printf("Metadata: %v\n", metadata)
}

Complete Example

Go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    gqldb "github.com/ultipa/ultipa-go-driver/v6"
)

func main() {
    config := gqldb.NewConfigBuilder().
        Hosts("localhost:9000").
        Timeout(30 * time.Second).
        Build()

    client, err := gqldb.NewClient(config)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()
    client.Login(ctx, "admin", "password")
    client.CreateGraph(ctx, "typeDemo", gqldb.GraphTypeOpen, "")
    client.UseGraph(ctx, "typeDemo")

    // Insert data with various types
    client.Gql(ctx, `
        INSERT (u:User {
            _id: 'u1',
            name: 'Alice',
            age: 30,
            balance: 1234.56,
            active: true,
            joined: DATE('2023-01-15'),
            location: POINT(40.7128, -74.0060),
            tags: ['developer', 'mentor'],
            settings: {theme: 'dark', notifications: true}
        })
    `, nil)

    // Query and check types
    response, _ := client.Gql(ctx, `
        MATCH (u:User {_id: 'u1'})
        RETURN u.name, u.age, u.balance, u.active, u.joined,
               u.location, u.tags, u.settings
    `, nil)

    row := response.First()
    if row != nil {
        name, _ := row.GetString(0)
        age, _ := row.GetInt(1)
        balance, _ := row.GetFloat(2)
        active, _ := row.GetBool(3)
        joined, _ := row.Get(4)
        location, _ := row.Get(5)
        tags, _ := row.Get(6)
        settings, _ := row.Get(7)

        fmt.Printf("Name (string): %s\n", name)
        fmt.Printf("Age (int64): %d\n", age)
        fmt.Printf("Balance (float64): %.2f\n", balance)
        fmt.Printf("Active (bool): %v\n", active)
        fmt.Printf("Joined: %v\n", joined)
        fmt.Printf("Location: %v\n", location)
        fmt.Printf("Tags: %v\n", tags)
        fmt.Printf("Settings: %v\n", settings)

        // Check property types
        fmt.Println("\nProperty types:")
        for i, tv := range row.Values {
            fmt.Printf("  Column %d: %v\n", i, tv.Type)
        }
    }

    client.DropGraph(ctx, "typeDemo", true)
}