Feature/query iso week year (#1091)

* Added documentation for feature/disallow-smart-index-fields * added documentation for feature/query-iso-week-year * Removed unrelated changes * Update 3.11/aql/functions-date.md Co-authored-by: Jan <jsteemann@users.noreply.github.com> * Changed key name * Review * Add data type * Update functions-date.md * Update release-notes-new-features311.md * Update examples for 3.11 in feature/query-iso-week-year at 2022-08-19T16:08:29+00:00 * Revert "Update examples for 3.11 in feature/query-iso-week-year at 2022-08-19T16:08:29+00:00" This reverts commit 5081ef2. * Update examples for 3.11 in feature/query-iso-week-year at 2022-08-24T15:15:37+00:00 Co-authored-by: Jan <jsteemann@users.noreply.github.com> Co-authored-by: Simran Spiller <simran@arangodb.com> Co-authored-by: Simran <Simran-B@users.noreply.github.com> Co-authored-by: ansoboleva <93702078+ansoboleva@users.noreply.github.com> Co-authored-by: arangodb-release-bot <anastasia.soboleva@arangodb.com>

Author: 4 people

3.11/aql/functions-date.md

@@ -438,10 +438,10 @@ Return the day of year of *date*.
 
 `DATE_ISOWEEK(date) → weekDate`
 
-Return the week date of *date* according to ISO 8601.
+Return the week number in the year of *date* according to ISO 8601.
 
 - **date** (number\|string): numeric timestamp or ISO 8601 date time string
-- returns **weekDate** (number): the ISO week date of *date*. The return values
+- returns **weekDate** (number): the ISO week number of *date*. The return values
  range from 1 to 53. Monday is considered the first day of the week. There are no
  fractional weeks, thus the last days in December may belong to the first week of
  the next year, and the first days in January may be part of the previous year's
@@ -458,6 +458,45 @@ Return the week date of *date* according to ISO 8601.
 {% endaqlexample %}
 {% include aqlexample.html id=examplevar type=type query=query bind=bind result=result %}
 
+### DATE_ISOWEEKYEAR()
+
+`DATE_ISOWEEKYEAR(date) → weekAndYear`
+
+Return the week number of *date* according to ISO 8601 and the year the
+week belongs to.
+
+- **date** (number\|string): numeric timestamp or ISO 8601 date time string
+- returns **weekAndYear** (object): an object with two attributes
+ - **week** (number): the ISO week number of *date*. The values range from 1 to 53.
+ Monday is considered the first day of the week. There are no fractional weeks,
+ thus the last days in December may belong to the first week of the next year,
+ and the first days in January may be part of the previous year's last week.
+ - **year** (number): the year to which the ISO week number belongs to
+
+**Examples**
+
+January 1st of 2023 is part of the previous year's last week:
+
+ {% aqlexample examplevar="examplevar" type="type" query="query" bind="bind" result="result" %}
+ @startDocuBlockInline aqlDateIsoWeekYear1
+ @EXAMPLE_AQL{aqlDateIsoWeekYear1}
+  RETURN DATE_ISOWEEKYEAR("2023-01-01")
+ @END_EXAMPLE_AQL
+ @endDocuBlock aqlDateIsoWeekYear1
+ {% endaqlexample %}
+ {% include aqlexample.html id=examplevar type=type query=query bind=bind result=result %}
+
+The last two days of 2019 are part of the next year's first week:
+
+ {% aqlexample examplevar="examplevar" type="type" query="query" bind="bind" result="result" %}
+ @startDocuBlockInline aqlDateIsoWeekYear2
+ @EXAMPLE_AQL{aqlDateIsoWeekYear2}
+  RETURN DATE_ISOWEEKYEAR("2019-12-30")
+ @END_EXAMPLE_AQL
+ @endDocuBlock aqlDateIsoWeekYear2
+ {% endaqlexample %}
+ {% include aqlexample.html id=examplevar type=type query=query bind=bind result=result %}
+
 ### DATE_LEAPYEAR()
 
 `DATE_LEAPYEAR(date) → leapYear`
@@ -686,8 +725,8 @@ Format a date according to the given format string.
 - %fff – millisecond (000..999), padded to length of 3
 - %x – day of year (1..366)
 - %xxx – day of year (001..366), padded to length of 3
-- %k – ISO week date (1..53)
-- %kk – ISO week date (01..53), padded to length of 2
+- %k – ISO week number of year (1..53)
+- %kk – ISO week number of year (01..53), padded to length of 2
 - %l – leap year (0 or 1)
 - %q – quarter (1..4)
 - %a – days in month (28..31)

3.11/generated/Examples/001_collectionAll.generated

@@ -2,62 +2,62 @@ arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/110&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;110&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065a--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKq--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;two&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/112&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;112&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;three&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/114&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;114&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;four&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/116&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;116&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e--A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu--A&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;five&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/118&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;118&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e--B&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu--B&quot;</span> 
 }
 arangosh&gt; db.five.all().toArray();
 [ 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;110&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/110&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065a--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKq--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;one&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;112&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/112&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e---&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu---&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;two&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;114&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/114&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;three&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;116&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/116&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e--A&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu--A&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;four&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;118&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/118&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6065e--B&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozKu--B&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;five&quot;</span> 
  } 
 ]

3.11/generated/Examples/002_collectionAllNext.generated

@@ -2,44 +2,44 @@ arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/130&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;130&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;two&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/132&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;132&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;three&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/134&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;134&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S--A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi--A&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;four&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/136&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;136&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S--B&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi--B&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;five&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/138&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;138&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S--C&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi--C&quot;</span> 
 }
 arangosh&gt; db.five.all().limit(<span class="hljs-number">2</span>).toArray();
 [ 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;130&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/130&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S---&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi---&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;one&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;132&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/132&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066S--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozLi--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;two&quot;</span> 
  } 
 ]

3.11/generated/Examples/003_collectionByExample.generated

@@ -2,38 +2,38 @@ arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/150&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;150&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6---&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Helmut&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/152&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;152&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6--_&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Angela&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/154&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;154&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i--A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6--A&quot;</span> 
 }
 arangosh&gt; db.users.all().toArray();
 [ 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;150&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/150&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i---&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6---&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Gerhard&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;152&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/152&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Helmut&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;154&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/154&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i--A&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6--A&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Angela&quot;</span> 
  } 
 ]
@@ -44,7 +44,7 @@ arangosh&gt; db.users.byExample({ <span class="hljs-string">&quot;name&quot;</sp
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;150&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/150&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066i---&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozL6---&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Gerhard&quot;</span> 
  } 
 ]

3.11/generated/Examples/004_collectionByExampleNext.generated

@@ -2,25 +2,25 @@ arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/172&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;172&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq6066y--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozMK--_&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Helmut&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/174&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;174&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq60662---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozMO---&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Angela&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/176&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;176&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq60662--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozMO--_&quot;</span> 
 }
 arangosh&gt; <span class="hljs-keyword">var</span> a = db.users.byExample( {<span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Angela&quot;</span> } );
 arangosh&gt; <span class="hljs-keyword">while</span> (a.hasNext()) print(a.next());
 { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;176&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/176&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_eq60662--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_er_ozMO--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Angela&quot;</span> 
 }