Add timedelta option, fix timezone issues.

Naive datetime objects are now universally interpreted as localtime
on the python client side. We had to do this because we need to
figure out UTC time for uuids on the python side when generating
from a datetime. Its awkward to have some things interpreted as
local time on the python side while others as localtime on the db
side. So all interpretation is done in python now.

We recommend using aware datetime objects in any case, such objects
have no ambiguity.

Author: cevian

nbs/00_vector.ipynb

@@ -67,6 +67,7 @@
     "import random\n",
     "from datetime import timedelta\n",
     "from datetime import datetime\n",
+    "from datetime import timezone\n",
     "import calendar"
    ]
   },
@@ -102,6 +103,10 @@
     "    if time_arg is None:\n",
     "        return uuid.uuid1(node, clock_seq)\n",
     "    if hasattr(time_arg, 'utctimetuple'):\n",
+    "        # this is different from the Cassandra version, we assume that a naive datetime is in system time and convert it to UTC\n",
+    "        # we do this because naive datetimes are interpreted as timestamps (without timezone) in postgres\n",
+    "        if time_arg.tzinfo is None:\n",
+    "            time_arg = time_arg.astimezone(timezone.utc)\n",
     "        seconds = int(calendar.timegm(time_arg.utctimetuple()))\n",
     "        microseconds = (seconds * 1e6) + time_arg.time().microsecond\n",
     "    else:\n",
@@ -291,21 +296,43 @@
    "source": [
     "#| export\n",
     "class UUIDTimeRange:\n",
-    "    def __init__(self, start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, start_inclusive=True, end_inclusive=False):\n",
+    "    def __init__(self, start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, time_delta: Optional[timedelta] = None, start_inclusive=True, end_inclusive=False):\n",
     "        \"\"\"\n",
-    "         A UUIDTimeRange is a time range predicate on the UUID Version 1 timestamps.\n",
+    "         A UUIDTimeRange is a time range predicate on the UUID Version 1 timestamps. \n",
+    "         \n",
+    "         Note that naive datetime objects are interpreted as local time on the python client side and converted to UTC before being sent to the database.\n",
     "        \"\"\"\n",
     "        if start_date is not None and end_date is not None:\n",
     "            if start_date > end_date:\n",
     "                raise Exception(\"start_date must be before end_date\")\n",
     "        \n",
     "        if start_date is None and end_date is None:\n",
     "            raise Exception(\"start_date and end_date cannot both be None\")\n",
+    "        \n",
+    "        if start_date is not None and start_date.tzinfo is None:\n",
+    "            start_date = start_date.astimezone(timezone.utc)\n",
+    "\n",
+    "        if end_date is not None and end_date.tzinfo is None:\n",
+    "            end_date = end_date.astimezone(timezone.utc)\n",
+    "        \n",
+    "        if time_delta is not None:\n",
+    "            if end_date is None:\n",
+    "                end_date = start_date + time_delta\n",
+    "            elif start_date is None:\n",
+    "                start_date = end_date - time_delta\n",
+    "            else:\n",
+    "                raise Exception(\"time_delta, start_date and end_date cannot all be specified at the same time\")\n",
     "\n",
     "        self.start_date = start_date\n",
     "        self.end_date = end_date\n",
     "        self.start_inclusive = start_inclusive\n",
     "        self.end_inclusive = end_inclusive\n",
+    "    \n",
+    "    def __str__(self):\n",
+    "        start_str = f\"[{self.start_date}\" if self.start_inclusive else f\"({self.start_date}\"\n",
+    "        end_str = f\"{self.end_date}]\" if self.end_inclusive else f\"{self.end_date})\"\n",
+    "        \n",
+    "        return f\"UUIDTimeRange {start_str}, {end_str}\"\n",
     "\n",
     "    def build_query(self, params: List) -> Tuple[str, List]:\n",
     "        column = \"uuid_timestamp(id)\"\n",
@@ -1135,6 +1162,18 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/cevian/.pyenv/versions/3.11.4/envs/nbdev_env/lib/python3.11/site-packages/fastcore/docscrape.py:225: UserWarning: potentially wrong underline length... \n",
+      "Returns \n",
+      "-------- in \n",
+      "Retrieves similar records using a similarity query.\n",
+      "...\n",
+      "  else: warn(msg)\n"
+     ]
+    },
     {
      "data": {
       "text/markdown": [
@@ -1409,6 +1448,13 @@
     "assert len(rec) == 0\n",
     "rec = await vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(specific_datetime-timedelta(days=7)))\n",
     "assert len(rec) == 2\n",
+    "rec = await vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(start_date=specific_datetime, time_delta=timedelta(days=7)))\n",
+    "assert len(rec) == 1\n",
+    "#end is exclusive\n",
+    "rec = await vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(end_date=specific_datetime, time_delta=timedelta(days=7)))\n",
+    "assert len(rec) == 0\n",
+    "rec = await vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(end_date=specific_datetime+timedelta(seconds=1), time_delta=timedelta(days=7)))\n",
+    "assert len(rec) == 1\n",
     "await vec.drop_table()\n",
     "await vec.close()"
    ]
@@ -2105,6 +2151,13 @@
     "assert len(rec) == 0\n",
     "rec = vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(specific_datetime-timedelta(days=7)))\n",
     "assert len(rec) == 2\n",
+    "rec = vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(start_date=specific_datetime, time_delta=timedelta(days=7)))\n",
+    "assert len(rec) == 1\n",
+    "#end is exclusive\n",
+    "rec =  vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(end_date=specific_datetime, time_delta=timedelta(days=7)))\n",
+    "assert len(rec) == 0\n",
+    "rec = vec.search([1.0, 2.0], limit=4, uuid_time_filter=UUIDTimeRange(end_date=specific_datetime+timedelta(seconds=1), time_delta=timedelta(days=7)))\n",
+    "assert len(rec) == 1\n",
     "vec.drop_table()\n",
     "vec.close()"
    ]

timescale_vector/_modidx.py

@@ -149,6 +149,8 @@
                                                                                     'timescale_vector/client.py'),
                                          'timescale_vector.client.UUIDTimeRange.__init__': ( 'vector.html#uuidtimerange.__init__',
                                                                                              'timescale_vector/client.py'),
+                                         'timescale_vector.client.UUIDTimeRange.__str__': ( 'vector.html#uuidtimerange.__str__',
+                                                                                            'timescale_vector/client.py'),
                                          'timescale_vector.client.UUIDTimeRange.build_query': ( 'vector.html#uuidtimerange.build_query',
                                                                                                 'timescale_vector/client.py'),
                                          'timescale_vector.client.uuid_from_time': ( 'vector.html#uuid_from_time',

timescale_vector/client.py

@@ -16,6 +16,7 @@
 import random
 from datetime import timedelta
 from datetime import datetime
+from datetime import timezone
 import calendar
 
 # %% ../nbs/00_vector.ipynb 6
@@ -44,6 +45,10 @@ def uuid_from_time(time_arg = None, node=None, clock_seq=None):
     if time_arg is None:
         return uuid.uuid1(node, clock_seq)
     if hasattr(time_arg, 'utctimetuple'):
+        # this is different from the Cassandra version, we assume that a naive datetime is in system time and convert it to UTC
+        # we do this because naive datetimes are interpreted as timestamps (without timezone) in postgres
+        if time_arg.tzinfo is None:
+            time_arg = time_arg.astimezone(timezone.utc)
         seconds = int(calendar.timegm(time_arg.utctimetuple()))
         microseconds = (seconds * 1e6) + time_arg.time().microsecond
     else:
@@ -195,21 +200,43 @@ def create_index_query(self, table_name_quoted:str, column_name_quoted: str, ind
 
 # %% ../nbs/00_vector.ipynb 11
 class UUIDTimeRange:
-    def __init__(self, start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, start_inclusive=True, end_inclusive=False):
+    def __init__(self, start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, time_delta: Optional[timedelta] = None, start_inclusive=True, end_inclusive=False):
         """
-         A UUIDTimeRange is a time range predicate on the UUID Version 1 timestamps.
+         A UUIDTimeRange is a time range predicate on the UUID Version 1 timestamps. 
+         
+         Note that naive datetime objects are interpreted as local time on the python client side and converted to UTC before being sent to the database.
         """
         if start_date is not None and end_date is not None:
             if start_date > end_date:
                 raise Exception("start_date must be before end_date")
 
         if start_date is None and end_date is None:
             raise Exception("start_date and end_date cannot both be None")
+        
+        if start_date is not None and start_date.tzinfo is None:
+            start_date = start_date.astimezone(timezone.utc)
+
+        if end_date is not None and end_date.tzinfo is None:
+            end_date = end_date.astimezone(timezone.utc)
+        
+        if time_delta is not None:
+            if end_date is None:
+                end_date = start_date + time_delta
+            elif start_date is None:
+                start_date = end_date - time_delta
+            else:
+                raise Exception("time_delta, start_date and end_date cannot all be specified at the same time")
 
         self.start_date = start_date
         self.end_date = end_date
         self.start_inclusive = start_inclusive
         self.end_inclusive = end_inclusive
+    
+    def __str__(self):
+        start_str = f"[{self.start_date}" if self.start_inclusive else f"({self.start_date}"
+        end_str = f"{self.end_date}]" if self.end_inclusive else f"{self.end_date})"
+        
+        return f"UUIDTimeRange {start_str}, {end_str}"
 
     def build_query(self, params: List) -> Tuple[str, List]:
         column = "uuid_timestamp(id)"