Merge pull request #148 from weaviate/jose/object-ttl

Add support for object_ttl in weaviate-cli.

Author: jfrancoa

.claude/skills/operating-weaviate-cli/SKILL.md

@@ -139,9 +139,29 @@ weaviate-cli delete collection --collection MyCollection --json
 weaviate-cli delete collection --all --json
 ```
 
-Key create options: `--multitenant`, `--auto_tenant_creation`, `--auto_tenant_activation`, `--shards N`, `--vectorizer <type>`, `--named_vector`, `--replication_deletion_strategy`
+Key create options: `--multitenant`, `--auto_tenant_creation`, `--auto_tenant_activation`, `--shards N`, `--vectorizer <type>`, `--named_vector`, `--replication_deletion_strategy`, `--object_ttl_type`, `--object_ttl_time`, `--object_ttl_filter_expired`, `--object_ttl_property_name` (only when `object_ttl_type=property`)
 
-Mutable fields: `--async_enabled`, `--replication_factor`, `--vector_index`, `--description`, `--training_limit`, `--auto_tenant_creation`, `--auto_tenant_activation`, `--replication_deletion_strategy`
+Mutable fields: `--async_enabled`, `--replication_factor`, `--vector_index`, `--description`, `--training_limit`, `--auto_tenant_creation`, `--auto_tenant_activation`, `--replication_deletion_strategy`, `--object_ttl_type`, `--object_ttl_time`, `--object_ttl_filter_expired`, `--object_ttl_property_name` (only when `object_ttl_type=property`)
+
+#### Object TTL
+
+```bash
+# Create with timestamp-based TTL (requires inverted_index timestamp for existing collections)
+weaviate-cli create collection --collection MyTTL --inverted_index timestamp --object_ttl_type create --object_ttl_time 3600 --json
+
+# Create with property-based TTL (date property, time=0 means expire at exact property date)
+weaviate-cli create collection --collection MyTTL --object_ttl_type property --object_ttl_time 0 --object_ttl_property_name expiresAt --json
+
+# Enable TTL on existing collection
+weaviate-cli update collection --collection MyTTL --object_ttl_type create --object_ttl_time 3600 --object_ttl_filter_expired true --json
+
+# Disable TTL (use "disable", not "disabled")
+weaviate-cli update collection --collection MyTTL --object_ttl_type disable --json
+```
+
+TTL types: `create` (by `_creationTimeUnix`), `update` (by `_lastUpdateTimeUnix`), `property` (by custom date property), `disable`
+
+**Note**: `--object_ttl_time` is in seconds. Value of `0` is valid for property type (expire at exact date). Timestamp types (`create`/`update`) require a minimum of 60 seconds.
 
 See [references/collections.md](references/collections.md) for full options.
 
@@ -161,6 +181,8 @@ Key data options: `--consistency_level`, `--auto_tenants N`, `--tenants "T1,T2"`
 
 Key query options: `--properties "title,keywords"`, `--tenants "T1"`, `--target_vector "default"`, `--consistency_level`
 
+**Note**: `--consistency_level` values must be **lowercase**: `one`, `quorum`, `all` (not `ONE`, `QUORUM`, `ALL`).
+
 See [references/data.md](references/data.md) and [references/search.md](references/search.md).
 
 ### Tenants
@@ -222,6 +244,8 @@ weaviate-cli delete user --user_name test-user --json
 
 Permission format: `action:target`. See [references/rbac.md](references/rbac.md) for full permission reference.
 
+**Shell quoting**: Permissions with wildcards must be quoted to prevent shell globbing: `-p 'crud_data:*'` (not `-p crud_data:*`, which fails in zsh with `no matches found`).
+
 ### Cluster & Nodes
 
 ```bash
@@ -305,11 +329,14 @@ hot/active  <-->  cold/inactive
 - Data operations require tenants in `hot`/`active` state
 
 ### RBAC Workflow
-1. `create role --role_name X -p <permission>` -- create role with permissions
-2. `create user --user_name Y` -- create user (returns API key)
+1. `create role --role_name X -p '<permission>'` -- create role with permissions (quote wildcards!)
+2. `create user --user_name Y --store` -- create user and auto-save API key into active config
 3. `assign role --role_name X --user_name Y` -- assign role to user
 4. Verify: `get role --role_name X` and `get user --user_name Y`
-5. Cleanup: `revoke role` -> `delete role` / `delete user`
+5. Test as new user: `weaviate-cli --config-file <config> --user Y <command> --json`
+6. Cleanup: `revoke role` -> `delete role` / `delete user`
+
+**Prerequisite**: The Weaviate cluster must be deployed with `DYNAMIC_USERS=true` for `create user` to work. Without it, only static API key users (configured at deploy time) are available.
 
 ### Backup Workflow
 1. `create backup --backend s3 --backup_id my-backup --wait` -- wait for completion
@@ -325,6 +352,14 @@ hot/active  <-->  cold/inactive
 5. `cancel replication <UUID>` -- cancel if needed
 6. `delete replication <UUID>` -- cleanup completed operation
 
+### Object TTL Workflow
+1. `create collection --object_ttl_type create --object_ttl_time 3600` -- create with TTL (or `update collection` to enable later)
+2. TTL requires server-side `objects_ttl_delete_schedule` runtime config to be set (e.g., `@every 10s`)
+3. `get collection --collection X` -- verify `objectTtlConfig` in response
+4. `update collection --object_ttl_type disable` -- disable TTL (stops background deletion)
+5. For timestamp-based TTL on existing collections: `--inverted_index timestamp` must be set at creation or already enabled
+6. For property-based TTL: the date property must exist, be `date` type, and have filterable or rangeable index
+
 ### Alias Workflow
 1. `create collection --collection Movies_v1` -- create the target collection
 2. `create alias Movies Movies_v1` -- create alias pointing to collection

.claude/skills/operating-weaviate-cli/references/collections.md

@@ -39,6 +39,25 @@ weaviate-cli create collection \
 - `--named_vector` -- Enable named vectors
 - `--named_vector_name` -- Named vector name (default: "default")
 - `--replication_deletion_strategy` -- delete_on_conflict, no_automated_resolution, time_based_resolution
+- `--object_ttl_type` -- TTL event type: create, update, property (default: "create")
+- `--object_ttl_time` -- Time to live in seconds (default: None, TTL disabled when omitted)
+- `--object_ttl_filter_expired` -- Filter expired-but-not-yet-deleted objects from queries
+- `--object_ttl_property_name` -- Date property name for TTL when `object_ttl_type=property` (default: "releaseDate"). **Only valid when `--object_ttl_type=property`**; rejected otherwise.
+
+**Object TTL examples:**
+```bash
+# Delete objects 1 hour after creation
+weaviate-cli create collection --collection Movies --object_ttl_type create --object_ttl_time 3600
+
+# Delete objects 24 hours after last update, filtering expired objects
+weaviate-cli create collection --collection Movies --object_ttl_type update --object_ttl_time 86400 --object_ttl_filter_expired
+
+# Delete objects based on default date property (releaseDate)
+weaviate-cli create collection --collection Movies --object_ttl_type property --object_ttl_time 0
+
+# Delete objects based on a custom date property (e.g. for clusters not using weaviate-cli schema)
+weaviate-cli create collection --collection MyCollection --object_ttl_type property --object_ttl_time 86400 --object_ttl_property_name expiresAt --json
+```
 
 ## Update Collection (mutable fields only)
 ```bash
@@ -49,10 +68,28 @@ weaviate-cli update collection \
   --json
 ```
 
-Mutable fields: `--async_enabled`, `--replication_factor`, `--vector_index`, `--description`, `--training_limit`, `--auto_tenant_creation`, `--auto_tenant_activation`, `--replication_deletion_strategy`
+Mutable fields: `--async_enabled`, `--replication_factor`, `--vector_index`, `--description`, `--training_limit`, `--auto_tenant_creation`, `--auto_tenant_activation`, `--replication_deletion_strategy`, `--object_ttl_type`, `--object_ttl_time`, `--object_ttl_filter_expired`, `--object_ttl_property_name` (only when `object_ttl_type=property`)
 
 **Immutable (cannot change after creation):** multitenant, vectorizer, named_vector, shards
 
+**Object TTL options for update:**
+- `--object_ttl_type` -- TTL event type: create, update, property, **disable** (default: "create")
+- `--object_ttl_time` -- Time to live in seconds (set together with type to enable TTL)
+- `--object_ttl_filter_expired` -- Filter expired-but-not-yet-deleted objects (type: bool)
+- `--object_ttl_property_name` -- Date property name when `object_ttl_type=property` (default: "releaseDate"). **Only valid when `--object_ttl_type=property`**; rejected otherwise.
+
+**Object TTL examples:**
+```bash
+# Enable TTL: delete objects 2 hours after creation
+weaviate-cli update collection --collection Movies --object_ttl_type create --object_ttl_time 7200
+
+# Disable TTL on an existing collection
+weaviate-cli update collection --collection Movies --object_ttl_type disable
+
+# Set TTL by custom date property on an existing collection
+weaviate-cli update collection --collection MyCollection --object_ttl_type property --object_ttl_time 86400 --object_ttl_property_name expiresAt --json
+```
+
 ## Delete Collection
 ```bash
 weaviate-cli delete collection --collection "MyCollection" --json

.github/workflows/main.yaml

@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
+        version: [ "3.10", "3.11", "3.12", "3.13" ]
     steps:
     - uses: actions/checkout@v5
     - uses: actions/setup-python@v6
@@ -67,7 +67,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
+        version: [ "3.10", "3.11", "3.12", "3.13" ]
     steps:
     - uses: actions/checkout@v5
     - uses: actions/setup-python@v6
@@ -96,7 +96,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
+        version: [ "3.10", "3.11", "3.12", "3.13" ]
     steps:
     - uses: actions/checkout@v5
     - uses: actions/setup-python@v6

setup.cfg

@@ -37,7 +37,7 @@ classifiers =
 include_package_data = True
 python_requires = >=3.9
 install_requires =
-    weaviate-client>=4.16.7
+    weaviate-client>=4.19.0
     click==8.1.7
     semver>=3.0.2
     numpy>=1.24.0