Date.WeekOfYear
DateReturns the week number within the year (1–54) for the given date.
Syntax
Date.WeekOfYear(dateTime as any, optional firstDayOfWeek as nullable number) as nullable numberParameters
| Name | Type | Required | Description |
|---|---|---|---|
dateTime | any | Yes | A date, datetime, or datetimezone value. |
firstDayOfWeek | number | No | A Day.* constant specifying the first day of the week. Defaults to Day.Sunday (0). Use Day.Monday (1) for ISO weeks. |
Return Value
number — An integer from 1 to 54 representing the week number within the year.
Remarks
Date.WeekOfYear returns the week number within the calendar year, starting from 1. Week 1 is always the week containing January 1. The optional firstDayOfWeek parameter controls which day starts a new week — default is Day.Sunday (0). Always use the Day.* enum constants rather than integer literals to keep code readable. If the input is null, the function returns null.
Be aware that Date.WeekOfYear uses a simple sequential week-counting rule rather than the ISO 8601 standard. ISO 8601 defines week 1 as the week containing the first Thursday of the year, which means January 1 may fall in week 52 or 53 of the previous year in ISO numbering. If you need true ISO week numbers, you will need a custom calculation using Date.StartOfWeek with Day.Monday.
Date.WeekOfYear is useful for week-over-week trend analysis and for creating weekly grouping keys alongside the year. Combine with Date.Year to build a year-week key such as "2024-W03" for consistent period labeling.
Examples
Example 1: Add week number to Sales table
Table.AddColumn(
Table.SelectColumns(
Table.FirstN(Sales, 5),
{"OrderID", "OrderDate"}
),
"WeekOfYear", each Date.WeekOfYear([OrderDate], Day.Sunday), Int64.Type
)OrderID | OrderDate | WeekOfYear | |
|---|---|---|---|
| 1 | 1 | 1/15/2024 | 3 |
| 2 | 2 | 1/18/2024 | 3 |
| 3 | 3 | 2/1/2024 | 5 |
| 4 | 4 | 2/10/2024 | 6 |
| 5 | 5 | 3/5/2024 | 10 |
Example 2: Week of year with Monday start
#table(
type table [Date = date, WeekOfYear = number],
{{#date(2024, 3, 15), Date.WeekOfYear(#date(2024, 3, 15), Day.Monday)}}
)Date | WeekOfYear | |
|---|---|---|
| 1 | 3/15/2024 | 11 |
Example 3: Build a year-week period label
Table.AddColumn(
Table.SelectColumns(Table.FirstN(Sales, 5), {"OrderID", "OrderDate"}),
"YearWeek",
each
Text.From(Date.Year([OrderDate])) & "-W"
& Text.PadStart(Text.From(Date.WeekOfYear([OrderDate], Day.Sunday)), 2, "0"),
type text
)OrderID | OrderDate | YearWeek | |
|---|---|---|---|
| 1 | 1 | 1/15/2024 | 2024-W03 |
| 2 | 2 | 1/18/2024 | 2024-W03 |
| 3 | 3 | 2/1/2024 | 2024-W05 |
| 4 | 4 | 2/10/2024 | 2024-W06 |
| 5 | 5 | 3/5/2024 | 2024-W10 |