schema

Documentation

Overview

Package schema defines the schema used for complex, stateful query generation.

The schema holds the current query context as well as an approximation of the current DB state. It holds information like the current variables as well as their types and graph elements like properties, labels and relationship types.

Additionally, it holds information about certain important values, which ensure syntactic correctness (e.g. IsUnionAll).

The schema provides some helper functions to ensure that values are correctly inserted and kept track of.

Index

• Constants
• type ExpressionConfig
• type ExpressionType
• type Function
• type Property
• type PropertyType
• type PropertyVariable
• type Schema
  • func (s *Schema) AddProperty(property Property)
  • func (s *Schema) AddPropertyVariable(variable PropertyVariable)
  • func (s *Schema) AddStructuralVariable(variable StructuralVariable)
  • func (s Schema) Copy() *Schema
  • func (s Schema) NewContext() *Schema
  • func (s Schema) NewSubContext() *Schema
  • func (s *Schema) Reset()
  • func (s *Schema) ResetContext()
• type StructuralType
• type StructuralVariable

Constants

const (
	// If this mask is used, the expression can NOT be null
	NullableMask int = 0x8000
	ListMask     int = 0x4000
)

Masks for property types

Types

type ExpressionConfig

type ExpressionConfig struct {
	// If this expression cannot evaluate to null
	MustBeNonNull bool
	// If this expression represents a list of the underlying type
	IsList bool
	// The type of this expression
	TargetType     ExpressionType
	PropertyType   PropertyType   // Only relevant if targetType != STRUCTURAL
	StructuralType StructuralType // Only relevant if targetType != PROPERTY
	// Constant expressions aren't allowed to contain variables
	IsConstantExpression bool
	// If this is expression is allowed to contain aggregating functions, for example in a RETURN or WITH statement
	CanContainAggregatingFunctions bool
	// If this expression is allowed to evaluate to a map
	AllowMaps bool
}

The ExpressionConfig holds all options dictating how an expression gets generated.

type ExpressionType

type ExpressionType int

The ExpressionType dictates whether an expression evaluates to a property or structural value.

const (
	// AnyExpression indicates the expression can evaluate to any expression type
	AnyExpression ExpressionType = iota
	// PropertyValue indicates the expression can only evaluate to a property value
	PropertyValue
	// StructuralValue indicates the expression can only evaluate to a structural value
	StructuralValue
)

type Function

type Function struct {
	// The function's name
	Name string
	// The expression configs for the function arguments
	InputTypes []ExpressionConfig
	// If true, this function can always return null even if arguments are all non null
	CanAlwaysBeNull bool
}

The Function struct represents a function callable in a cypher query. Its return type gets defined in the implementation-specific OpenCypher config.

type Property

type Property struct {
	Name  string
	Type  PropertyType
	Value string
}

Property represents a node's or relationship's property

type PropertyType

type PropertyType int

PropertyType represents a type for a Cypher expression If the 16th bit is set, the expression can NOT be null If the 15th bit is set, the expression is a list of the underlying type

const (
	Boolean PropertyType = iota + 1
	Date
	Datetime
	Duration
	Float
	Integer
	LocalDateTime
	LocalTime
	Point
	String
	Time
)

Types defined by OpenCypher

const (
	// For LIMIT & SKIP
	PositiveInteger PropertyType = iota + 12
	// For percentileCont and percentileDisc functions
	Percentile
	// For substring
	Int32
	// For round function precision
	PositiveInt32
)

Types used for more accurate generation

const (
	// AnyType indicates the expression can evaluate to any type
	AnyType PropertyType = iota
)

type PropertyVariable

type PropertyVariable struct {
	Name  string
	Type  PropertyType
	Value string
}

A PropertyVariable represents any variable evaluating to a property value.

type Schema

type Schema struct {
	// Lists the names of all properties used in a graph element
	Properties         map[PropertyType][]Property
	PropertyTypeByName map[string]PropertyType
	// Lists all labels used for a graph element
	Labels map[StructuralType][]string
	// Whether the statement already has an OPTIONAL MATCH clause (disallows further use of normal MATCH clauses)
	HasOptionalMatch bool

	// Added because of https://github.com/neo4j/neo4j/issues/13054
	IsInSubquery bool

	// There are two label match types in neo4j, the old one (only allowing ANDing labels by separating them with a colon)
	// And the new one, allowing complex expressions with negation, ORing and ANDing labels, plus adding wildcards
	// According to [Neo4j Docs], every clause must use the same label match type
	// If this value is unset, it is not yet decided which type to use for this clause
	// The RootClause and WriteQuery must reset this value to nil during generation
	//
	// [Neo4j Docs]: https://neo4j.com/docs/cypher-manual/current/syntax/expressions/#syntax-restrictions-label
	UseNewLabelMatchType *bool

	// If set, this decides whether the unions should be UNION ALL clauses or just UNION clauses
	IsUnionAll *bool

	// If true, expressions are not allowed to evaluate to NULL or contain subquery expressions (COUNT/EXISTS/COLLECT)
	IsInMergeClause bool

	// If true, expressions are not allowed to contain aggregate functions
	DisallowAggregateFunctions bool
	// If this is set, the clause `RETURN *` will never be generated
	DisallowReturnAll bool

	// Map of all used names in the query, used to ensure their uniqueness
	UsedNames *map[string]bool

	// Allows UNION clauses and having CALL subqueries return variables
	MustReturn                  bool // If MustReturn is true, the statement has to terminate with a RETURN clause
	PropertyVariablesToReturn   []PropertyVariable
	StructuralVariablesToReturn []StructuralVariable

	// Property variables (ints, floats, strings, etc) hold variables created using WITH or UNWIND statements and can be used everywhere
	PropertyVariablesByName map[string]PropertyVariable         // Holds property variables, searchable via name
	PropertyVariablesByType map[PropertyType][]PropertyVariable // Holds property variables, collected via type

	// Structural variables (nodes, relationships and paths) can only be used in RETURN and WHERE statements
	StructuralVariablesByName map[string]StructuralVariable           // Holds structural variables, searchable via name
	StructuralVariablesByType map[StructuralType][]StructuralVariable // Holds structural variables, collected via type

	// Holds structural variables that just got created in a CREATE clause, which can't be used in functions in the same clause
	JustCreatedStructuralVariables []StructuralVariable

	// Names of created indexes
	Indexes []string
}

The Schema used for stateful query generation

func (*Schema) AddProperty

func (s *Schema) AddProperty(property Property)

AddProperty adds a new (node or relationship) property to the abstract graph state

func (*Schema) AddPropertyVariable

func (s *Schema) AddPropertyVariable(variable PropertyVariable)

AddPropertyVariable adds a property variable to the schema.

func (*Schema) AddStructuralVariable

func (s *Schema) AddStructuralVariable(variable StructuralVariable)

AddStructuralVariable adds a structural variable to the schema.

func (Schema) Copy

func (s Schema) Copy() *Schema

Copy returns a deep copy of the schema

func (Schema) NewContext

func (s Schema) NewContext() *Schema

NewContext creates and returns a new context by resetting the query context but preserving the abstract graph state.

func (Schema) NewSubContext

func (s Schema) NewSubContext() *Schema

NewSubContext creates and returns a schema which is a subcontext relative to the given schema. It keeps variables and relevant flags.

func (*Schema) Reset

func (s *Schema) Reset()

Reset sets the schema back to an initial state.

It should only be called by the driver, not during clause generation. For creating a new context, use NewContext() instead.

func (*Schema) ResetContext

func (s *Schema) ResetContext()

ResetContext resets the schema's context by resetting fields populated during generation

type StructuralType

type StructuralType int

StructuralType specifies the exact type of a structural variable.

const (
	ANY StructuralType = iota
	NODE
	RELATIONSHIP
	PATH
)

Structural Types

type StructuralVariable

type StructuralVariable struct {
	Name string
	Type StructuralType
	// If this variable is likely to evaluate to nil.
	// If unset, then the variable is guaranteed to be non nil.
	LikelyNull bool
}

A StructuralVariable represents any variable evaluating to a structural value.