Built-in Functions

On this page

String Functions
Numeric Functions
Temporal Functions
List Functions
Vector Functions
Other Functions

Cypher comes with a variety of built-in functions that can be used to manipulate and process data within a query. This section will cover the most commonly used functions in Cypher, including string, numeric, temporal, list functions and others.

String Functions

Cypher has several functions for manipulating string values:

UPPER and LOWER: Convert a string to upper or lower case.

RETURN UPPER('hello'), LOWER('WORLD') // Returns 'HELLO', 'world'

SUBSTRING: Extract a substring from a string.

RETURN SUBSTRING('Hello, world!', 0, 5) // Returns 'Hello'

TRIM: Remove whitespace from the beginning and end of a string.
```
RETURN TRIM('  hello  ') // Returns 'hello'
```

REPLACE: Replace all occurrences of a substring within a string.

RETURN REPLACE('Hello, world!', 'world', 'Cypher') // Returns 'Hello, Cypher!'

Numeric Functions

Cypher provides functions for performing mathematical operations:

ABS: Returns the absolute value of a number.
```
RETURN ABS(-5) // Returns 5
```
ROUND, FLOOR, and CEIL: Round a number to the nearest integer, down to the nearest integer, or up to the nearest integer.
```
RETURN ROUND(3.14), FLOOR(3.14), CEIL(3.14) // Returns 3, 3, 4
```
SQRT: Returns the square root of a number.
```
RETURN SQRT(9) // Returns 3
```

Temporal Functions

Cypher also includes functions for working with dates and times:

DATE: Create a date value.
```
RETURN DATE('2023-05-18')
```
TIME: Create a time value.
```
RETURN TIME('12:34:56')
```
DATETIME: Create a date-time value.
```
RETURN DATETIME('2023-05-18T12:34:56')
```

duration.between: Calculate the duration between two date, time, or date-time values.

RETURN duration.between(DATE('2023-05-18'), DATE('2023-06-18')) // Returns 'P31D'

List Functions

Cypher provides several functions for working with list values:

SIZE: Return the number of elements in a list.
```
RETURN SIZE([1, 2, 3]) // Returns 3
```

COLLECT: Aggregate values into a list.

MATCH (p:Person)
RETURN COLLECT(p.name)

RANGE: Create a list of integers within a range.

RETURN RANGE(1, 5) // Returns [1, 2, 3, 4, 5]

Vector Functions

There is one function to rank vector properties. The function expects exactly three arguments as shown below. The function’s result is an ordinary scalar, so it works in RETURN, WHERE and ORDER BY like any other value.

Syntax: vector_distance(vector1, vector2, vectorDistanceMetric)

Description: Returns a DOUBLE representing the distance between the two vector values based on the selected vectorDistanceMetric algorithm.

Arguments:

Name	Type
`vector1`	list of numbers or booleans
`vector2`	list of numbers or booleans
`vectorDistanceMetric`	`[L1, L2, COSINE, INNER_PRODUCT, HAMMING, JACCARD, CHISQUARED, L2SQUARED]`

Note that the HAMMING and JACCARD metrics require boolean lists and the others lists of numbers.
vectorDistanceMetric must be a string literal.

When using vector_distance, the distance calculations are never pushed down but are always computed inside Polypheny, even if the store supports it natively. This means that querying data stored on a PostgreSQL store with the pgvector extension will not result in a pushdown to this store, even when an SQL query of the same data would.

Example

MATCH (n:Order)
RETURN n.id, vector_distance(n.embedding, [1.0, 2.0, 3.0], 'L2') AS score
ORDER BY score ASC
LIMIT 10

This returns the nodes from Order with the property embedding being closest to the query vector when using the L2 metric.

Other Functions

There are many other functions available in Cypher, for handling different types of data and operations. A few examples include:

TYPE: Return the type of a relationship.
```
MATCH (a)-[r]->(b)
RETURN TYPE(r)
```

ID: Return the internal ID of a node or relationship.

MATCH (p:Person { name: 'John Doe' })
RETURN ID(p)

EXISTS: Check if a property or path exists.

MATCH (p:Person { name: 'John Doe' })
RETURN EXISTS(p.age)

Aggregating Data

Advanced Topics