GcsJsonDb
Store sessions, memories, metrics, knowledge, evals, and traces as JSON files in Google Cloud Storage.
GcsJsonDb is a class that implements the Db interface using Google Cloud Storage as the backend storage system. Each table is stored as a JSON file in a GCS bucket.
| Parameter | Type | Default | Description |
|---|---|---|---|
id | Optional[str] | - | Database ID. Derived deterministically from bucket, project and prefix when omitted. |
bucket_name | str | - | Name of the GCS bucket where JSON files will be stored. |
prefix | Optional[str] | - | Path prefix for organizing files in the bucket. Defaults to "agno/". |
session_table | Optional[str] | - | Name of the JSON file to store sessions (without .json extension). |
runs_table | Optional[str] | None | Storage name for individual runs. Defaults to agno_runs, or <session_table>_runs when a custom session name is supplied. |
memory_table | Optional[str] | - | Name of the JSON file to store user memories. |
metrics_table | Optional[str] | - | Name of the JSON file to store metrics. |
eval_table | Optional[str] | - | Name of the JSON file to store evaluation runs. |
knowledge_table | Optional[str] | - | Name of the JSON file to store knowledge content. |
traces_table | Optional[str] | - | Name of the JSON file to store traces. |
spans_table | Optional[str] | - | Name of the JSON file to store spans. |
project | Optional[str] | - | GCP project ID. If None, uses default project. |
credentials | Optional[Any] | - | GCP credentials. If None, uses default credentials. |
Methods
upsert_sessions
Upsert multiple sessions in one method call.
Parameters:
sessions(List[Session]): List of sessions to upsertdeserialize(Optional[bool]): Whether to deserialize the sessions. Defaults toTruepreserve_updated_at(bool): Request preservation of the sessions' existingupdated_attimestamps; see adapter limitations below. Defaults toFalse
Returns: List[Union[Session, Dict[str, Any]]]
upsert_memories
Upsert multiple memories in one method call.
Parameters:
memories(List[UserMemory]): List of memories to upsertdeserialize(Optional[bool]): Whether to deserialize the memories. Defaults toTruepreserve_updated_at(bool): Request preservation of the memories' existingupdated_attimestamps; see adapter limitations below. Defaults toFalse
Returns: List[Union[UserMemory, Dict[str, Any]]]
Timestamp preservation by adapter
JsonDb, GcsJsonDb, FirestoreDb, RedisDb, DynamoDb, and InMemoryDb accept preserve_updated_at but do not forward it to their individual upserts. Their bulk methods replace timestamps even when it is True.
PostgresDb, SingleStoreDb, and ValkeyDb honor the flag. MySQLDb, SqliteDb, and MongoDb honor it on their optimized bulk path; their per-record fallback paths do not forward it. Verify timestamps when a migration depends on preserving them.
GcsJsonDb accepts multiple records through the bulk methods but processes each record with an individual upsert. These methods do not reduce GCS read and write operations. In the current implementation, preserve_updated_at is accepted but ignored, so an upsert replaces the existing timestamp.