From a00478a8152409ecaea0bfe055d5da664a27f472 Mon Sep 17 00:00:00 2001 From: Albert Safin Date: Tue, 5 Mar 2024 01:32:39 +0000 Subject: [PATCH 1/5] docs: datetime payload --- .../documentation/concepts/filtering.md | 84 +++++++++++++++++++ .../documentation/concepts/indexing.md | 3 +- .../content/documentation/concepts/payload.md | 29 +++++++ 3 files changed, 115 insertions(+), 1 deletion(-) diff --git a/qdrant-landing/content/documentation/concepts/filtering.md b/qdrant-landing/content/documentation/concepts/filtering.md index 34af04fd9..f58865ed1 100644 --- a/qdrant-landing/content/documentation/concepts/filtering.md +++ b/qdrant-landing/content/documentation/concepts/filtering.md @@ -1747,6 +1747,90 @@ Comparisons that can be used: Can be applied to [float](../payload/#float) and [integer](../payload/#integer) payloads. +### Datetime Range + +_Available as of v1.8.0_ + +```json +{ + "key": "date", + "range": { + "gt": "2023-02-08T10:49:00Z" + "gte": null, + "lt": null, + "lte": "2024-01-31 10:14:31Z" + } +} +``` + +```python +models.FieldCondition( + key="date", + range=models.DatetimeRange( + gt="2023-02-08T10:49:00Z", + gte=None, + lt=None, + lte="2024-01-31T10:14:31Z", + ), +) +``` + +```typescript +{ + key: 'date', + range: { + gt: '2023-02-08T10:49:00Z', + gte: null, + lt: null, + lte: '2024-01-31T10:14:31Z' + } +} +``` + +```rust +Condition::datetime_range( + "date", + DatetimeRange { + gt: Some(Timestamp::date_time(2023, 2, 8, 10, 49, 0).unwrap()), + gte: None, + lt: None, + lte: Some(Timestamp::date_time(2024, 1, 31, 10, 14, 31).unwrap()), + }, +) +``` + +```java +import static io.qdrant.client.ConditionFactory.datetimeRange; + +import com.google.protobuf.Timestamp; +import io.qdrant.client.grpc.Points.DatetimeRange; +import java.time.Instant; + +long gt = Instant.parse("2023-02-08T10:49:00Z").getEpochSecond(); +long lte = Instant.parse("2024-01-31T10:14:31Z").getEpochSecond(); + +datetimeRange("date", + DatetimeRange.newBuilder() + .setGt(Timestamp.newBuilder().setSeconds(gt)) + .setLte(Timestamp.newBuilder().setSeconds(lte)) + .build()); +``` + +```csharp +using Qdrant.Client.Grpc; +using System; + +Conditions.DatetimeRange( + field: "date", + gt: new DateTime(2023, 2, 8, 10, 49, 0, DateTimeKind.Utc), + lte: new DateTime(2024, 1, 31, 10, 14, 31, DateTimeKind.Utc), +); +``` + +Datetime range is a special case of the range condition, which is used for [datetime](../payload/#datetime) payloads. +It shares the same field names as the range condition. +During comparison, timestamps are parsed and converted to UTC. + ### Geo #### Geo Bounding Box diff --git a/qdrant-landing/content/documentation/concepts/indexing.md b/qdrant-landing/content/documentation/concepts/indexing.md index 30f9bccaf..08b4c5129 100644 --- a/qdrant-landing/content/documentation/concepts/indexing.md +++ b/qdrant-landing/content/documentation/concepts/indexing.md @@ -105,8 +105,9 @@ Available field types are: * `keyword` - for [keyword](../payload/#keyword) payload, affects [Match](../filtering/#match) filtering conditions. * `integer` - for [integer](../payload/#integer) payload, affects [Match](../filtering/#match) and [Range](../filtering/#range) filtering conditions. * `float` - for [float](../payload/#float) payload, affects [Range](../filtering/#range) filtering conditions. -* `bool` - for [bool](../payload/#bool) payload, affects [Match](../filtering/#match) filtering conditions (available as of 1.4.0). +* `bool` - for [bool](../payload/#bool) payload, affects [Match](../filtering/#match) filtering conditions (available as of v1.4.0). * `geo` - for [geo](../payload/#geo) payload, affects [Geo Bounding Box](../filtering/#geo-bounding-box) and [Geo Radius](../filtering/#geo-radius) filtering conditions. +* `datetime` - for [datetime](../payload/#datetime) payload, affects [Range](../filtering/#range) filtering conditions (available as of v1.8.0). * `text` - a special kind of index, available for [keyword](../payload/#keyword) / string payloads, affects [Full Text search](../filtering/#full-text-match) filtering conditions. Payload index may occupy some additional memory, so it is recommended to only use index for those fields that are used in filtering conditions. diff --git a/qdrant-landing/content/documentation/concepts/payload.md b/qdrant-landing/content/documentation/concepts/payload.md index e79211446..f9f491586 100644 --- a/qdrant-landing/content/documentation/concepts/payload.md +++ b/qdrant-landing/content/documentation/concepts/payload.md @@ -137,6 +137,35 @@ Example of single and multiple `geo` values: Coordinate should be described as an object containing two fields: `lon` - for longitude, and `lat` - for latitude. +### Datetime + +*Available as of v1.8.0* + +`datetime` - date and time in [RFC 3339] format. + +Example of single and multiple `datetime` values: + +```json +{ + "created_at": "2023-02-08T10:49:00Z", + "updated_at": [ + "2023-02-08T13:52:00Z", + "2023-02-21T21:23:00Z" + ] +} +``` + +The following formats are supported: +- `"2023-02-08T10:49:00Z"` ([RFC 3339], UTC) +- `"2023-02-08T11:49:00+01:00"` ([RFC 3339], with timezone) +- `"2023-02-08T10:49:00"` (without timezone, UTC is assumed) +- `"2023-02-08T10:49"` (without timezone and seconds) +- `"2023-02-08"` (only date, midnight is assumed) + +The `T` and `Z` symbols are case-insensitive, and `T` can be replaced with a space. + +[RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 + ## Create point with payload REST API ([Schema](https://qdrant.github.io/qdrant/redoc/index.html#tag/points/operation/upsert_points)) From 1d4e3d27fb946f3fa964e5e664c2fab02ffbec54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Vis=C3=A9e?= Date: Wed, 6 Mar 2024 11:28:52 +0100 Subject: [PATCH 2/5] Update qdrant-landing/content/documentation/concepts/filtering.md --- qdrant-landing/content/documentation/concepts/filtering.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/qdrant-landing/content/documentation/concepts/filtering.md b/qdrant-landing/content/documentation/concepts/filtering.md index f58865ed1..d12bb8b43 100644 --- a/qdrant-landing/content/documentation/concepts/filtering.md +++ b/qdrant-landing/content/documentation/concepts/filtering.md @@ -1749,6 +1749,9 @@ Can be applied to [float](../payload/#float) and [integer](../payload/#integer) ### Datetime Range +The datetime range is a unique range condition, used for [datetime](../payload/#datetime) payloads, which supports RFC 3339 formats. +You do not need to convert dates to UNIX timestaps. During comparison, timestamps are parsed and converted to UTC. + _Available as of v1.8.0_ ```json From 9ed077c0e756265fd2224ba2b3151d2b7091c40c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Vis=C3=A9e?= Date: Wed, 6 Mar 2024 11:29:04 +0100 Subject: [PATCH 3/5] Update qdrant-landing/content/documentation/concepts/payload.md Co-authored-by: Mike Jang --- qdrant-landing/content/documentation/concepts/payload.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qdrant-landing/content/documentation/concepts/payload.md b/qdrant-landing/content/documentation/concepts/payload.md index f9f491586..08cfb4930 100644 --- a/qdrant-landing/content/documentation/concepts/payload.md +++ b/qdrant-landing/content/documentation/concepts/payload.md @@ -143,7 +143,7 @@ Coordinate should be described as an object containing two fields: `lon` - for l `datetime` - date and time in [RFC 3339] format. -Example of single and multiple `datetime` values: +See the following examples of single and multiple `datetime` values: ```json { From d3a6649b1a2474c961893f4bd1fa09e9d1a5dc47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Vis=C3=A9e?= Date: Wed, 6 Mar 2024 11:29:20 +0100 Subject: [PATCH 4/5] Update qdrant-landing/content/documentation/concepts/filtering.md Co-authored-by: Anush --- qdrant-landing/content/documentation/concepts/filtering.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/qdrant-landing/content/documentation/concepts/filtering.md b/qdrant-landing/content/documentation/concepts/filtering.md index d12bb8b43..f93cb0f64 100644 --- a/qdrant-landing/content/documentation/concepts/filtering.md +++ b/qdrant-landing/content/documentation/concepts/filtering.md @@ -1821,12 +1821,11 @@ datetimeRange("date", ```csharp using Qdrant.Client.Grpc; -using System; Conditions.DatetimeRange( field: "date", gt: new DateTime(2023, 2, 8, 10, 49, 0, DateTimeKind.Utc), - lte: new DateTime(2024, 1, 31, 10, 14, 31, DateTimeKind.Utc), + lte: new DateTime(2024, 1, 31, 10, 14, 31, DateTimeKind.Utc) ); ``` From 2024cf6ae3f4447516ebf175fc7dcd2207756d50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Vis=C3=A9e?= Date: Wed, 6 Mar 2024 11:29:41 +0100 Subject: [PATCH 5/5] Update qdrant-landing/content/documentation/concepts/filtering.md Co-authored-by: Mike Jang --- qdrant-landing/content/documentation/concepts/filtering.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/qdrant-landing/content/documentation/concepts/filtering.md b/qdrant-landing/content/documentation/concepts/filtering.md index f93cb0f64..1fd776b16 100644 --- a/qdrant-landing/content/documentation/concepts/filtering.md +++ b/qdrant-landing/content/documentation/concepts/filtering.md @@ -1829,10 +1829,6 @@ Conditions.DatetimeRange( ); ``` -Datetime range is a special case of the range condition, which is used for [datetime](../payload/#datetime) payloads. -It shares the same field names as the range condition. -During comparison, timestamps are parsed and converted to UTC. - ### Geo #### Geo Bounding Box