Enhance Python examples and dataset handling

- Updated README.md for examples to include NULL handling and improved data type descriptions.
- Added download_sample_data.py to automate downloading and modifying the MovieLens dataset, introducing NULL values for testing.
- Updated pyproject.toml to change the Bug Tracker link to the new repository.

Author: tae898

README.md

@@ -24,6 +24,8 @@ pip install arcadedb-embedded           # With Gremlin + GraphQL
 
 **Requirements:** Python 3.8+ and [Java 21+](https://adoptium.net/) (JRE)
 
+**💡 Tip:** See "JVMCI is not enabled" warnings? Install [GraalVM](https://humemai.github.io/arcadedb-embedded-python/latest/getting-started/installation/#eliminate-polyglot-warnings-optional) to fix them
+
 **Technology:** Uses [JPype](https://jpype.readthedocs.io/) to bridge Python and Java, providing direct access to ArcadeDB's embedded engine with minimal overhead.
 
 ### Basic Usage (CRUD)

bindings/python/README.md

@@ -39,6 +39,9 @@ pip install arcadedb-embedded
 
 **Requirements**: Java 21+ must be installed ([details](https://humemai.github.io/arcadedb-embedded-python/latest/getting-started/installation/#java-runtime-environment-jre))
 
+!!! tip "Eliminate JVMCI Warnings"
+    See warnings about "JVMCI is not enabled"? Install [GraalVM](https://humemai.github.io/arcadedb-embedded-python/latest/getting-started/installation/#eliminate-polyglot-warnings-optional) to fix them.
+
 ### 5-Minute Example
 
 ```python

bindings/python/docs/development/troubleshooting.md

@@ -824,12 +824,12 @@ else:
    - [Examples](../examples/import.md)
 
 2. **Search Issues:**
-   - [GitHub Issues](https://github.com/ArcadeData/arcadedb/issues)
+   - [GitHub Issues](https://github.com/humemai/arcadedb-embedded-python/issues)
    - [ArcadeDB Documentation](https://docs.arcadedb.com/)
 
 3. **Ask Community:**
    - [Discord](https://discord.gg/arcadedb)
-   - [GitHub Discussions](https://github.com/ArcadeData/arcadedb/discussions)
+   - [GitHub Discussions](https://github.com/humemai/arcadedb-embedded-python/discussions)
 
 4. **Report Bug:**
    Include:

bindings/python/docs/examples/01_simple_document_store.md

@@ -1,16 +1,18 @@
 # Simple Document Store Example
 
-This comprehensive example demonstrates ArcadeDB's document capabilities using real-world scenarios. You'll learn about data types, SQL functions, and the differences between document and graph storage models.
+This comprehensive example demonstrates ArcadeDB's document capabilities using a task management system. You'll learn about data types, NULL handling, SQL operations, and the differences between document and graph storage models.
 
 ## Overview
 
-The example creates a product catalog system showcasing:
+The example creates a task management system showcasing:
 
-- **Rich Data Types** - STRING, BOOLEAN, INTEGER, FLOAT, DECIMAL, DATE, DATETIME, BINARY, EMBEDDED, LINK, Arrays
-- **SQL Functions** - uuid(), date(), sysdate() for dynamic data generation
+- **Rich Data Types** - STRING, BOOLEAN, INTEGER, FLOAT, DECIMAL, DATE, DATETIME, LIST OF STRING, and Arrays
+- **NULL Handling** - INSERT with NULL, UPDATE to NULL, queries with IS NULL/IS NOT NULL
+- **SQL Operations** - Complete CRUD workflow with ArcadeDB SQL
+- **Built-in Functions** - date() for date literals, uuid() for unique IDs, sysdate() for dynamic timestamps
 - **Record Types** - Understanding Documents vs Vertices vs Edges
-- **Schema Evolution** - Adding typed properties for performance and validation
-- **CRUD Operations** - Complete create, read, update, delete workflow
+- **Schema Flexibility** - Typed properties for performance with schema-optional flexibility
+- **Type Safety** - LIST OF STRING for validated array data
 
 ## Source Code
 
@@ -20,37 +22,64 @@ The complete example is available at: [`examples/01_simple_document_store.py`](.
 
 ### 1. Data Type Support
 
-ArcadeDB provides comprehensive data type support:
+ArcadeDB provides comprehensive data type support with NULL handling:
 
 ```python
-# Schema with typed properties for performance
+# Schema with typed properties for performance and validation
+with db.transaction():
+    db.command("sql", "CREATE DOCUMENT TYPE Task")
+    db.command("sql", "CREATE PROPERTY Task.title STRING")
+    db.command("sql", "CREATE PROPERTY Task.priority STRING")
+    db.command("sql", "CREATE PROPERTY Task.completed BOOLEAN")
+    db.command("sql", "CREATE PROPERTY Task.tags LIST OF STRING")  # Type-safe arrays
+    db.command("sql", "CREATE PROPERTY Task.created_date DATE")
+    db.command("sql", "CREATE PROPERTY Task.due_datetime DATETIME")
+    db.command("sql", "CREATE PROPERTY Task.estimated_hours FLOAT")
+    db.command("sql", "CREATE PROPERTY Task.priority_score INTEGER")
+    db.command("sql", "CREATE PROPERTY Task.cost DECIMAL")
+    db.command("sql", "CREATE PROPERTY Task.task_id STRING")
+
+# Insert with NULL values for optional fields and uuid() for unique ID
 db.command("sql", """
-CREATE DOCUMENT TYPE Product (
-    name STRING,
-    description STRING,
-    price DECIMAL,
-    in_stock BOOLEAN,
-    category_id INTEGER,
-    weight FLOAT,
-    created_at DATETIME,
-    tags STRING[],
-    metadata EMBEDDED
-)
+    INSERT INTO Task SET
+        title = 'Write documentation',
+        priority = 'medium',
+        completed = false,
+        tags = ['work', 'writing'],
+        created_date = date('2024-01-16'),
+        due_datetime = NULL,
+        estimated_hours = 8.0,
+        priority_score = 70,
+        cost = NULL,
+        task_id = uuid()
 """)
 ```
 
-### 2. SQL Functions
+### 2. SQL Functions and NULL Queries
 
-Learn about built-in functions for dynamic data:
+Learn about built-in functions and NULL handling:
 
 ```python
-# UUID generation and date functions
-result = db.command("sql", """
-INSERT INTO Product SET
-    id = uuid(),
-    name = 'Laptop Pro',
-    created_at = sysdate(),
-    launch_date = date('2024-01-15', 'yyyy-MM-dd')
+# Built-in functions: date() for DATE type, uuid() for unique IDs
+db.command("sql", """
+    INSERT INTO Task SET
+        title = 'Buy groceries',
+        task_id = uuid(),
+        created_date = date('2024-01-15'),
+        due_datetime = '2024-01-20 18:00:00',
+        cost = 150.00
+""")
+
+# Query for NULL values
+result = db.query("sql", "SELECT FROM Task WHERE due_datetime IS NULL")
+result = db.query("sql", "SELECT FROM Task WHERE cost IS NULL")
+
+# UPDATE to set NULL (clear optional values)
+db.command("sql", """
+    UPDATE Task SET
+        cost = NULL,
+        estimated_hours = NULL
+    WHERE title = 'Call dentist'
 """)
 ```
 
@@ -66,10 +95,12 @@ Understanding when to use different record types:
 
 The example demonstrates:
 
-- **Embedded Documents** - Nested JSON-like structures
-- **Arrays** - Collections of values
-- **Schema Evolution** - Adding properties dynamically
-- **Query Optimization** - Using indexes and typed properties
+- **NULL Values** - Optional fields with IS NULL/IS NOT NULL queries
+- **Type-Safe Arrays** - LIST OF STRING for validated collections
+- **DECIMAL Handling** - Java BigDecimal conversion via float(str(value))
+- **DATETIME Literals** - String literals automatically parsed to DATETIME type
+- **Schema-Optional Flexibility** - Define properties for performance, add ad-hoc fields when needed
+- **Query Optimization** - Using typed properties and indexes
 
 ## Running the Example
 
@@ -79,21 +110,24 @@ python 01_simple_document_store.py
 ```
 
 Expected output includes:
+
 - Database creation and schema setup
-- Sample data insertion with various types
-- Query demonstrations
+- Sample tasks with various data types and NULL values
+- Query demonstrations including NULL checks
+- UPDATE operations setting values to NULL
 - File structure explanation
 
 ## Database Structure
 
 After running, examine the created files:
 
-```
-databases/product_catalog/
+```text
+my_test_databases/task_db/
 ├── configuration.json     # Database configuration
-├── schema.json           # Type definitions and indexes
-├── *.bucket             # Data storage files
-└── statistics.json      # Database statistics
+├── schema.json           # Type definitions with LIST OF STRING
+├── Task_*.bucket         # Data storage files with tasks
+├── dictionary.*.dict     # String compression dictionary
+└── statistics.json       # Database statistics
 ```
 
 ## Next Steps
@@ -106,15 +140,24 @@ After mastering this example:
 
 ## Common Questions
 
+**Q: How does ArcadeDB handle NULL values?**
+A: All ArcadeDB types support NULL by default. You can INSERT NULL, UPDATE to NULL, and query with IS NULL/IS NOT NULL operators.
+
+**Q: What's the difference between LIST and LIST OF STRING?**
+A: LIST is a generic untyped list. LIST OF STRING provides type validation ensuring all elements are strings, giving better performance and data integrity.
+
 **Q: Why use typed properties?**
-A: They provide better performance, validation, and enable advanced features like indexes.
+A: They provide better performance, validation, and enable advanced features like indexes. But ArcadeDB is schema-optional - you can still add properties dynamically.
 
 **Q: When should I use Documents vs Vertices?**
-A: Use Documents for simple data storage (like SQL tables). Use Vertices when you need to model relationships between entities.
+A: Use Documents for simple data storage (like SQL tables). Use Vertices when you need to model relationships between entities with Edges.
+
+**Q: How do I handle Java BigDecimal in Python?**
+A: Convert via string first: `float(str(decimal_value))`. Direct conversion from Java BigDecimal to Python float requires string intermediary.
 
 **Q: Can I mix data types?**
 A: Yes! ArcadeDB is schema-flexible. You can add properties dynamically while benefiting from typed properties where defined.
 
 ---
 
-*Need help? Check our [troubleshooting guide](../troubleshooting.md) or [open an issue](https://github.com/ArcadeData/arcadedb/issues).*
+*Need help? Check our [troubleshooting guide](../troubleshooting.md) or [open an issue](https://github.com/humemai/arcadedb-embedded-python/issues).*

bindings/python/docs/examples/02_social_network_graph.md

@@ -11,9 +11,12 @@ This example demonstrates how to use ArcadeDB as a graph database to model and q
 **What You'll Learn:**
 - Creating vertex and edge types (schema definition)
 - Modeling entities (Person) and relationships (FRIEND_OF) with properties
+- NULL value handling for optional vertex properties (email, phone, reputation)
 - Graph traversal patterns (friends, friends-of-friends, mutual connections)
-- Comparing SQL vs Cypher query languages for graph operations
+- Comparing SQL MATCH vs Cypher query languages for graph operations
+- Variable-length path queries (`*1..3` syntax in Cypher)
 - Working with relationship properties and bidirectional edges
+- Filtering by NULL values (finding people without email/phone)
 - Proper transaction handling and property access patterns
 - Real-world graph database implementation techniques
 
@@ -66,6 +69,11 @@ with db.transaction():
     db.command("sql", "CREATE PROPERTY Person.name STRING")
     db.command("sql", "CREATE PROPERTY Person.age INTEGER")
     db.command("sql", "CREATE PROPERTY Person.city STRING")
+    db.command("sql", "CREATE PROPERTY Person.joined_date DATE")
+    db.command("sql", "CREATE PROPERTY Person.email STRING")      # Optional (can be NULL)
+    db.command("sql", "CREATE PROPERTY Person.phone STRING")      # Optional (can be NULL)
+    db.command("sql", "CREATE PROPERTY Person.verified BOOLEAN")
+    db.command("sql", "CREATE PROPERTY Person.reputation FLOAT")  # Optional (can be NULL)
 
     # Create edge type with properties
     db.command("sql", "CREATE EDGE TYPE FRIEND_OF")
@@ -133,6 +141,53 @@ for row in result:
     print(f"Friend: {name} from {city}")
 ```
 
+## NULL Value Handling in Graphs
+
+Graph vertices can have optional properties with NULL values:
+
+```python
+# Insert person with NULL email and phone
+with db.transaction():
+    db.command("sql", """
+        CREATE VERTEX Person SET
+            name = 'Eve Brown',
+            age = 29,
+            city = 'Seattle',
+            joined_date = date('2020-08-22'),
+            email = NULL,
+            phone = NULL,
+            verified = false,
+            reputation = 3.2
+    """)
+```
+
+### Querying for NULL Values
+
+Find vertices with missing optional properties:
+
+```python
+# Find people without email addresses
+result = db.query("sql", """
+    SELECT name, phone, verified
+    FROM Person
+    WHERE email IS NULL
+""")
+
+# Find verified people with reputation scores (exclude NULLs)
+result = db.query("sql", """
+    SELECT name, reputation, city
+    FROM Person
+    WHERE verified = true AND reputation IS NOT NULL
+    ORDER BY reputation DESC
+""")
+```
+
+This pattern is useful for:
+- Finding incomplete profiles
+- Identifying missing contact information
+- Filtering by data completeness
+- Quality checks and data validation
+
 ## Advanced Graph Patterns
 
 ### Friends of Friends

bindings/python/docs/examples/03_vector_search.md

@@ -457,4 +457,4 @@ Until the implementation stabilizes, consider mature alternatives:
 
 ---
 
-*This example is educational and demonstrates current capabilities. Monitor [ArcadeDB releases](https://github.com/ArcadeData/arcadedb/releases) for vector search stability updates.*
+*This example is educational and demonstrates current capabilities. Monitor [ArcadeDB releases](https://github.com/humemai/arcadedb-embedded-python/releases) for vector search stability updates.*