Polishing

Author: cevian

README.md

@@ -1,4 +1,4 @@
-# python-vector
+# Timescale-vector
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
@@ -8,15 +8,76 @@ documentation.
 ## Install
 
 ``` sh
-pip install python_vector
+pip install timescale_vector
 ```
 
 ## How to use
 
-Fill me in please! Don’t forget code examples:
+Load up your postgres credentials. Safest way is with a .env file:
 
 ``` python
-1+1
+from dotenv import load_dotenv, find_dotenv
+import os
 ```
 
-    2
+``` python
+_ = load_dotenv(find_dotenv()) 
+connection_string  = os.environ['PG_CONNECTION_STRING']
+```
+
+Next, create the client.
+
+This takes three arguments: - A connection string - The name of the
+collection - Number of dimensions
+
+``` python
+vec  = client.Async(connection_string, "my_data", 2)
+```
+
+Next, create the tables for the collection:
+
+``` python
+await vec.create_tables()
+```
+
+Next, insert some data. The data record contains: - A uuid to uniquely
+identify the emedding - A json blob of metadata about the embedding -
+The text the embedding represents - The embedding itself
+
+Because this data already includes uuids we only allow upserts
+
+``` python
+import uuid
+```
+
+``` python
+await vec.upsert([\
+    (uuid.uuid4(), '''{"animal":"fox"}''', "the brown fox", [1.0,1.3]),\
+    (uuid.uuid4(), '''{"animal":"fox", "action":"jump"}''', "jumped over the", [1.0,10.8]),\
+])
+```
+
+Now you can query for similar items:
+
+``` python
+await vec.search([1.0, 9.0])
+```
+
+    [<Record id=UUID('25df4eea-a17f-42c2-9426-d09b8ca40e32') metadata='{"action": "jump", "animal": "fox"}' contents='jumped over the' embedding=array([ 1. , 10.8], dtype=float32) ?column?=0.00016793422934946456>,
+     <Record id=UUID('605e3ff5-3503-4006-826f-c84ecbb535d4') metadata='{"animal": "fox"}' contents='the brown fox' embedding=array([1. , 1.3], dtype=float32) ?column?=0.14489260377438218>]
+
+You can specify the number of records to return.
+
+``` python
+await vec.search([1.0, 9.0], k=1)
+```
+
+    [<Record id=UUID('25df4eea-a17f-42c2-9426-d09b8ca40e32') metadata='{"action": "jump", "animal": "fox"}' contents='jumped over the' embedding=array([ 1. , 10.8], dtype=float32) ?column?=0.00016793422934946456>]
+
+You can also specify a filter on the metadata as a simple dictionary
+
+``` python
+await vec.search([1.0, 9.0], k=1, filter={"action": "jump"})
+```
+
+    [<Record id=UUID('25df4eea-a17f-42c2-9426-d09b8ca40e32') metadata='{"action": "jump", "animal": "fox"}' contents='jumped over the' embedding=array([ 1. , 10.8], dtype=float32) ?column?=0.00016793422934946456>]