feat(examples): add usage examples for sqlite-vec-client

* Implement basic usage example
* Add batch operations example
* Create context manager example
* Include metadata filtering example
* Add persistent database example
* Implement real-world scenario example

Author: atasoglu

TODO

@@ -25,11 +25,11 @@
 - [ ] Mock tests (sqlite-vec extension)
 
 ### Examples
-- [ ] examples/basic_usage.py
-- [ ] examples/metadata_filtering.py
-- [ ] examples/batch_operations.py
-- [ ] examples/context_manager.py
-- [ ] examples/real_world_scenario.py
+- [x] examples/basic_usage.py
+- [x] examples/metadata_filtering.py
+- [x] examples/batch_operations.py
+- [x] examples/context_manager.py
+- [x] examples/real_world_scenario.py
 
 ### Documentation
 - [ ] Create CONTRIBUTING.md

examples/basic_usage.py

@@ -0,0 +1,58 @@
+"""Basic usage example for sqlite-vec-client.
+
+Demonstrates:
+- Creating a client and table
+- Adding texts with embeddings
+- Similarity search
+- Retrieving records
+"""
+
+from sqlite_vec_client import SQLiteVecClient
+
+
+def main():
+    # Initialize client
+    client = SQLiteVecClient(table="documents", db_path=":memory:")
+
+    # Create table with 384-dimensional embeddings
+    client.create_table(dim=384, distance="cosine")
+
+    # Sample texts and embeddings (384-dim vectors)
+    texts = [
+        "The quick brown fox jumps over the lazy dog",
+        "Machine learning is a subset of artificial intelligence",
+        "Python is a popular programming language",
+    ]
+
+    embeddings = [
+        [0.1, 0.2, 0.3] + [0.0] * 381,
+        [0.5, 0.4, 0.3] + [0.0] * 381,
+        [0.2, 0.1, 0.05] + [0.0] * 381,
+    ]
+
+    # Add records
+    rowids = client.add(texts=texts, embeddings=embeddings)
+    print(f"Added {len(rowids)} records: {rowids}")
+
+    # Similarity search
+    query_embedding = [0.1, 0.2, 0.3] + [0.0] * 381
+    results = client.similarity_search(embedding=query_embedding, top_k=2)
+
+    print("\nTop 2 similar documents:")
+    for rowid, text, distance in results:
+        print(f"  [{rowid}] {text[:50]}... (distance: {distance:.4f})")
+
+    # Get record by ID
+    record = client.get_by_id(rowids[0])
+    if record:
+        rowid, text, metadata, embedding = record
+        print(f"\nRecord {rowid}: {text}")
+
+    # Count total records
+    print(f"\nTotal records: {client.count()}")
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

examples/batch_operations.py

@@ -0,0 +1,54 @@
+"""Batch operations example for sqlite-vec-client.
+
+Demonstrates:
+- Bulk insert
+- Batch retrieval
+- Pagination
+- Bulk delete
+"""
+
+from sqlite_vec_client import SQLiteVecClient
+
+
+def main():
+    client = SQLiteVecClient(table="products", db_path=":memory:")
+    client.create_table(dim=64, distance="L2")
+
+    # Bulk insert
+    num_products = 100
+    texts = [f"Product {i} description" for i in range(num_products)]
+    embeddings = [[float(i % 10) / 10] * 64 for i in range(num_products)]
+    metadata = [{"product_id": i, "price": i * 10} for i in range(num_products)]
+
+    rowids = client.add(texts=texts, embeddings=embeddings, metadata=metadata)
+    print(f"Inserted {len(rowids)} products")
+
+    # Pagination - list first page
+    page_size = 10
+    page_1 = client.list_results(limit=page_size, offset=0, order="asc")
+    print(f"\nPage 1 ({len(page_1)} items):")
+    for rowid, text, meta, _ in page_1[:3]:
+        print(f"  [{rowid}] {text} - ${meta['price']}")
+
+    # Pagination - list second page
+    page_2 = client.list_results(limit=page_size, offset=page_size, order="asc")
+    print(f"\nPage 2 ({len(page_2)} items):")
+    for rowid, text, meta, _ in page_2[:3]:
+        print(f"  [{rowid}] {text} - ${meta['price']}")
+
+    # Batch retrieval
+    selected_ids = rowids[10:15]
+    selected_products = client.get_many(selected_ids)
+    print(f"\nRetrieved {len(selected_products)} specific products")
+
+    # Bulk delete
+    to_delete = rowids[:20]
+    deleted_count = client.delete_many(to_delete)
+    print(f"\nDeleted {deleted_count} products")
+    print(f"Remaining products: {client.count()}")
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

examples/context_manager.py

@@ -0,0 +1,44 @@
+"""Context manager example for sqlite-vec-client.
+
+Demonstrates:
+- Using client as context manager
+- Automatic connection cleanup
+- Exception handling
+"""
+
+from sqlite_vec_client import SQLiteVecClient
+
+
+def main():
+    # Using context manager - connection closes automatically
+    with SQLiteVecClient(table="notes", db_path=":memory:") as client:
+        client.create_table(dim=256, distance="cosine")
+
+        texts = ["First note", "Second note", "Third note"]
+        embeddings = [[0.1] * 256, [0.2] * 256, [0.3] * 256]
+
+        rowids = client.add(texts=texts, embeddings=embeddings)
+        print(f"Added {len(rowids)} notes")
+
+        # Search
+        results = client.similarity_search(embedding=[0.15] * 256, top_k=2)
+        print("\nTop 2 similar notes:")
+        for rowid, text, distance in results:
+            print(f"  [{rowid}] {text} (distance: {distance:.4f})")
+
+    # Connection is automatically closed here
+    print("\nConnection closed automatically")
+
+    # Exception handling with context manager
+    try:
+        with SQLiteVecClient(table="temp", db_path=":memory:") as client:
+            client.create_table(dim=128, distance="cosine")
+            # Simulate error
+            raise ValueError("Simulated error")
+    except ValueError as e:
+        print(f"\nHandled error: {e}")
+        print("Connection still closed properly despite exception")
+
+
+if __name__ == "__main__":
+    main()

examples/metadata_filtering.py

@@ -0,0 +1,70 @@
+"""Metadata filtering example for sqlite-vec-client.
+
+Demonstrates:
+- Adding records with metadata
+- Filtering by metadata
+- Filtering by text
+- Updating metadata
+"""
+
+from sqlite_vec_client import SQLiteVecClient
+
+
+def main():
+    client = SQLiteVecClient(table="articles", db_path=":memory:")
+    client.create_table(dim=128, distance="cosine")
+
+    # Add articles with metadata
+    texts = [
+        "Introduction to Python programming",
+        "Advanced machine learning techniques",
+        "Python for data science",
+    ]
+
+    embeddings = [
+        [0.1] * 128,
+        [0.2] * 128,
+        [0.15] * 128,
+    ]
+
+    metadata = [
+        {"category": "programming", "author": "Alice", "year": 2023},
+        {"category": "ai", "author": "Bob", "year": 2024},
+        {"category": "data-science", "author": "Alice", "year": 2024},
+    ]
+
+    rowids = client.add(texts=texts, embeddings=embeddings, metadata=metadata)
+    print(f"Added {len(rowids)} articles")
+
+    # Filter by exact metadata match
+    alice_articles = client.get_by_metadata(
+        {"category": "programming", "author": "Alice", "year": 2023}
+    )
+    print(f"\nAlice's programming articles: {len(alice_articles)}")
+    for rowid, text, meta, _ in alice_articles:
+        print(f"  [{rowid}] {text} - {meta}")
+
+    # Filter by text
+    python_articles = client.get_by_text("Python for data science")
+    print(f"\nPython articles: {len(python_articles)}")
+
+    # Update metadata
+    if rowids:
+        client.update(
+            rowids[0],
+            metadata={
+                "category": "programming",
+                "author": "Alice",
+                "year": 2024,
+                "updated": True,
+            },
+        )
+        updated = client.get_by_id(rowids[0])
+        if updated:
+            print(f"\nUpdated metadata: {updated[2]}")
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

examples/persistent_database.py

@@ -0,0 +1,50 @@
+"""Persistent database example for sqlite-vec-client.
+
+Demonstrates:
+- Creating a persistent .db file
+- Loading from existing .db file
+- Data persistence across sessions
+"""
+
+from sqlite_vec_client import SQLiteVecClient
+
+
+def create_database():
+    """Create and populate a persistent database."""
+    print("Creating database...")
+    client = SQLiteVecClient(table="documents", db_path="./my_vectors.db")
+    client.create_table(dim=128, distance="cosine")
+
+    texts = [
+        "First document",
+        "Second document",
+        "Third document",
+    ]
+    embeddings = [[0.1] * 128, [0.2] * 128, [0.3] * 128]
+
+    rowids = client.add(texts=texts, embeddings=embeddings)
+    print(f"Added {len(rowids)} documents")
+    print(f"Total records: {client.count()}")
+
+    client.close()
+
+
+def load_database():
+    """Load and query existing database."""
+    print("\nLoading existing database...")
+    client = SQLiteVecClient(table="documents", db_path="./my_vectors.db")
+
+    print(f"Total records: {client.count()}")
+
+    # Search
+    results = client.similarity_search(embedding=[0.15] * 128, top_k=2)
+    print("\nTop 2 results:")
+    for rowid, text, distance in results:
+        print(f"  [{rowid}] {text} (distance: {distance:.4f})")
+
+    client.close()
+
+
+if __name__ == "__main__":
+    create_database()
+    load_database()