{"id":19484950,"url":"https://github.com/opencog/atomspace-rocks","last_synced_at":"2026-04-02T01:57:46.603Z","repository":{"id":41981965,"uuid":"284504400","full_name":"opencog/atomspace-rocks","owner":"opencog","description":"AtomSpace Graph Database RocksDB backend","archived":false,"fork":false,"pushed_at":"2024-05-10T17:43:06.000Z","size":618,"stargazers_count":13,"open_issues_count":8,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-10T18:48:03.217Z","etag":null,"topics":["atomspace","file","opencog","persistance"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opencog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-02T17:00:16.000Z","updated_at":"2024-05-10T17:43:09.000Z","dependencies_parsed_at":"2024-04-02T03:39:54.077Z","dependency_job_id":"c742bbec-64b6-4ba1-9297-67acb4a2c17b","html_url":"https://github.com/opencog/atomspace-rocks","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-rocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-rocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-rocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencog%2Fatomspace-rocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opencog","download_url":"https://codeload.github.com/opencog/atomspace-rocks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224009948,"owners_count":17240651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomspace","file","opencog","persistance"],"created_at":"2024-11-10T20:24:51.577Z","updated_at":"2026-04-02T01:57:46.594Z","avatar_url":"https://github.com/opencog.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"AtomSpace RocksDB StorageNode\n=============================\n[![CircleCI](https://circleci.com/gh/opencog/atomspace-rocks.svg?style=svg)](https://circleci.com/gh/opencog/atomspace-rocks)\n\nSave and restore [AtomSpace](https://github.com/opencog/atomspace)\ncontents as well as individual Atoms to a\n[RocksDB](https://rocksdb.org) database. The RocksDB database is a\nhigh-performance, zero-configuration, single-user, local-host-only\nfile-backed database. It provides top-notch read and write performance,\nwhich is the #1 reason you should e interested in using it. But please\nnote: only one running AtomSpace executable can connect to it at any\ngiven moment. Multi-user, networked AtomSpaces are provided by the\n[AtomSpace-Cog](https://github.com/opencog/atomspace-cog) `StorageNode`\ndriver.\n\nIn ASCII-art:\n\n```\n +---------------------+\n |                     |\n |      AtomSpace      |\n |                     |\n +-- StorageNode API --+\n |                     |\n |  RocksStorageNode   |\n |                     |\n +---------------------+\n |       RocksDB       |\n +---------------------+\n |     filesystem      |\n +---------------------+\n```\nEach box is a shared library. Library calls go downwards. The\n[StorageNode API](https://wiki.opencog.org/w/StorageNode) is the same\nfor **all** `StorageNode`s; the `RocksStorageNode` is just one of them.\n\nRocksDB (see https://rocksdb.org/) is an \"embeddable persistent key-value\nstore for fast storage.\" The goal of layering the AtomSpace on top of it\nis to provide fast persistent storage for the AtomSpace.  There are\nseveral advantages to doing this:\n\n* RocksDB is file-based, and so it is straight-forward to make backup\n  copies of datasets, as well as to share these copies with others.\n  (You don't need to be a DB Admin to do this!)\n* RocksDB runs locally, and so the overhead of pushing bytes through\n  the network is eliminated. The remaining inefficiencies/bottlenecks\n  have to do with converting between the AtomSpace's natural in-RAM\n  format, and the position-independent format that all databases need.\n  (Here, we say \"position-independent\" in that the DB format does not\n  contain any C/C++ pointers; all references are managed with local\n  unique ID's.)\n* RocksDB is a \"real\" database, and so enables the storage of datasets\n  that might not otherwise fit into RAM. This back-end does not try\n  to guess what your working set is; it is up to you to load, work with\n  and save those Atoms that are important for you. The [examples](examples)\n  demonstrate exactly how that can be done.\n\nThis backend, together with the CogServer-based\n[network AtomSpace](https://github.com/opencog/atomspace-cog)\nbackend provides a building-block out of which more complex\ndistributed and/or decentralized AtomSpaces can be built.\n\n\nStatus\n------\nThis is ***Version 1.6.1***.  All unit tests pass.  It has been used in\nat least one major project, to process tens of millions of Atoms.\n\nThe list of changes since January 2024 is long and fairly boring;\nmostly bug fixes and patches forced by updates to the core AtomSpace.\nThe following changes are notable:\n\n* The `*-delete-*` message only deletes Atoms from the on-disk\n  AtomSpace DB.  Deleting from the local (in-RAM) AtomSpace must now\n  be performed as a distinct step.\n* Atoms that are used as keys or messages cannot be deleted.\n* The Python API has been fixed so it actually works. It uses the new\n  message-passing system.\n* The base `StorageNode` (provided by\n  [atomspace-storage](https://github.com/opencog/atomspace-storage))\n  now uses a message-passing system to perform all actions. Typical\n  messages include `*-open-*`, `*-close-*`, `*-load-atom-*`,\n  `*-store-atom-*` and so on. The same base set is supported by all\n  `StorageNode`s (and `ProxyNode`s), not just atomspace-rocks.\n  See the wiki pages for\n  [StorageNode](https://wiki.opencog.org/w/StorageNode) and\n  [ObjectNode](https://wiki.opencog.org/w/ObjectNode).\n* The `*open-ro-*` message is now supported, for read-only access.\n\n\nBuilding and Installing\n-----------------------\nRocksDB is a prerequisite. On Debian/Ubuntu, `apt install librocks-dev`\n\nThe build and install of `atomspace-rocks` follows the same pattern as\nother AtomSpace projects. Prerequisites include the AtomSpace itself\n(from https://github.com/opencog/atomspace) and the generic StorageNode\nAPI (from https://github.com/opencog/atomspace-storage).\n\nAll Atomese projects, including this one, use the same build, install\nand test pattern:\n```\n    cd to project dir atomspace-rocks\n    git pull\n    mkdir build\n    cd build\n    cmake ..\n    make -j\n    sudo make install\n    make -j check check ARGS=-j\n```\n\nExample Usage\n-------------\nSee the examples directory for details. In brief:\n\n```\n$ guile\nscheme@(guile-user)\u003e (use-modules (opencog))\nscheme@(guile-user)\u003e (use-modules (opencog persist))\nscheme@(guile-user)\u003e (use-modules (opencog persist-rocks))\nscheme@(guile-user)\u003e (define sto (RocksStorageNode \"rocks:///tmp/foo.rdb/\"))\nscheme@(guile-user)\u003e (cog-open sto)\nscheme@(guile-user)\u003e (load-atomspace)\nscheme@(guile-user)\u003e (cog-close sto)\n```\n\nThat's it! You've loaded the entire contents of `foo.rdb` into the\nAtomSpace!  Of course, loading everything is not generally desirable,\nespecially when the file is huge and RAM space is tight.  More granular\nload and store is possible; see the [examples directory](examples) for\ndetails.\n\nContents\n--------\nThere are two implementations in this repo: a simple one, suitable for\nusers who use only a single AtomSpace, and a sophisticated one, intended\nfor sophisticated users who need to work with complex DAG's of\nAtomSpaces. These two are accessed by using either `MonoStorageNode`\nor by using `RocksStorageNode`. Both use the standard\n[`StorageNode`](https://wiki.opencog.org/w/StorageNode) API.\n\nThe implementation of `MonoStorageNode` is smaller and simpler, and is\nthe easier of the two to understand.\n\nThe implementation of `RocksStorageNode` provides full support for deep\nstacks (DAG's) of AtomSpaces, layered one on top another (called\n\"Frames\", a name meant to suggest \"Kripke Frames\" and \"stackframes\").\nAn individual \"frame\" can be thought of as a change-set, a collection of\ndeltas to the next frame further down in the DAG. A frame inheriting\nfrom multiple AtomSpaces contains the set-union of Atoms in the\ncontributing AtomSpaces. Atoms and Values can added, changed and removed\nin each changeset, without affecting Atoms and Values in deeper frames.\n\nDesign\n------\nThis is a minimalistic implementation. There has been no performance\ntuning. There's only just enough code to make everything work; that's\nit. This does nothing at all fancy/sophisticated with RocksDB, and it\nmight be possible to improve performance and squeeze out some air.\nHowever, the code is not sloppy, so it might be hard to make it go\nfaster.\n\nIf you are creating a new StorageNode to some other kind of database,\nusing the code here as a starting point would make an excellent design\nchoice.  All the hard problems have been solved, and yet the overall\ndesign remains fairly simple.  All you'd need to do is to replace all\nof the references to RocksDB to your favorite, desired DB.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencog%2Fatomspace-rocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencog%2Fatomspace-rocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencog%2Fatomspace-rocks/lists"}