---
title: year
url: https://nexyron.tech/docs/cypher/functions/temporal/year
description: Extracts the year component from a temporal value. It is documented separately because time construction, sequence ordering, window parameters, and as of behavior materially change
---

# year

## Generic Description

Extracts the year component from a temporal value. It is documented separately because time construction, sequence ordering, window parameters, and as-of behavior materially change analytical meaning.

Simple example:

```cypher
RETURN year()
```

## Consumer-Level Explanation

Use it for calendar grouping when the year is the intended grain. Prefer this function when the temporal assumption should be visible to the planner, especially for event streams, freshness checks, and sequence features.

## More Detailed Explanation

`year` belongs to the temporal construction, conversion, or extraction surface. Use it to make time semantics explicit in the query text: whether a value is date-only, time-only, timestamp-like, duration-like, current-time dependent, or bucketed to a chosen calendar unit.

## Advanced Example

This example names the event stream and operational context before applying `year`, which helps planner tooling preserve the intended sequence semantics.

```cypher
MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     unpivot(properties(d.metadata)) AS metadata_rows,
     date_trunc('day', e.ts) AS day_bucket,
     year(e.ts) AS focused_value
RETURN u.user_id, d.title, day_bucket, metadata_rows, focused_value
LIMIT 10
```

## Real Use Cases

-   time-bucketed graph analytics
-   as-of filtering and event-window construction
-   making imported timestamp strings or epoch values typed before comparison

## Real Limitations And Tradeoffs

-   current-time functions are intentionally nondeterministic
-   timezone and local-time choices should be made explicit when results cross systems
-   extractors and truncation functions do not create temporal history; they only transform values already in the row