{"id":36863568,"url":"https://github.com/guycipher/btree","last_synced_at":"2026-01-12T14:51:58.647Z","repository":{"id":251125694,"uuid":"836467229","full_name":"guycipher/btree","owner":"guycipher","description":"A fast, disk-based BTree package with an extensive easy-to-use API optimized for large keys with many values.","archived":false,"fork":false,"pushed_at":"2024-12-24T12:26:04.000Z","size":129,"stargazers_count":81,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-24T13:53:38.470Z","etag":null,"topics":["btree","database","datastore","datastructure","embedded","golang","keyvaluestore"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/guycipher/btree","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guycipher.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":"2024-07-31T23:16:36.000Z","updated_at":"2024-12-24T12:24:38.000Z","dependencies_parsed_at":"2024-08-23T07:22:49.669Z","dependency_job_id":"54a2adca-4225-4087-9bf4-90696b8710ff","html_url":"https://github.com/guycipher/btree","commit_stats":null,"previous_names":["guycipher/btree"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/guycipher/btree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guycipher%2Fbtree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guycipher%2Fbtree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guycipher%2Fbtree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guycipher%2Fbtree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guycipher","download_url":"https://codeload.github.com/guycipher/btree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guycipher%2Fbtree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["btree","database","datastore","datastructure","embedded","golang","keyvaluestore"],"created_at":"2026-01-12T14:51:58.563Z","updated_at":"2026-01-12T14:51:58.634Z","avatar_url":"https://github.com/guycipher.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GO BTree\nA fast, simple disk based BTree implementation in Go.\n\nhttps://pkg.go.dev/github.com/guycipher/btree\n\n## Features\n- Easy to use API with `Put`, `Get`, `Delete`, `Remove`, `Iterator`, `Range` methods\n- Disk based storage with underlying pager\n- Supports keys with multiple values\n- Supports large keys and values\n\n## Extra features\n- `NGet` get's keys not equal to the key\n- `NRange` get's keys not equal to provided range\n- `GreaterThan` get's keys greater than the provided key\n- `GreaterThanEq` get's keys greater than or equal to the provided key\n- `LessThan` get's keys less than the provided key\n- `LessThanEq` get's keys less than or equal to the provided key\n\n\n```\ngoos: linux\ngoarch: amd64\npkg: github.com/guycipher/btree\ncpu: 11th Gen Intel(R) Core(TM) i7-11700K @ 3.60GHz\nBenchmarkBTree_Put\nBenchmarkBTree_Put-16    \t   10000\t    125006 ns/op\n```\n\n\u003e [!WARNING]\n\u003e Not thread safe.  You must handle concurrency control yourself.\n\n## Usage\n### Importing\n```\nimport \"github.com/guycipher/btree\"\n```\n\n### Creating a new BTree\n\nYou can use the ``Open`` method to open an existing btree or create a new one.\nYou can specify the file name, flags, file mode, and the degree of the btree.\n```go\nbt, err := btree.Open(\"btree.db\", os.O_CREATE|os.O_RDWR, 0644, 3)\nif err != nil {\n..\n}\n```\n\n### Inserting a key-value pair\n\nYou can insert a value into a key using the ``Put`` method.  Keys can store many values.\n```go\nerr := bt.Put([]byte(\"key\"), []byte(\"value\"))\nif err != nil {\n..\n}\n```\n\n### Getting a value\n\nTo get a value you can you the ``Get`` method.  The get method will return all the keys values.\n```go\nvalues, err := bt.Get([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n#### NGet\nTo get all keys not equal to the key you can use the ``NGet`` method.\n```go\nkeys, err := bt.NGet([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n### GreaterThan\nTo get all keys greater than the key you can use the ``GreaterThan`` method.\n```go\nkeys, err := bt.GreaterThan([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n### GreaterThanEq\nTo get all keys greater than or equal to the key you can use the ``GreaterThanEq`` method.\n```go\nkeys, err := bt.GreaterThanEq([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n### LessThan\nTo get all keys less than the key you can use the ``LessThan`` method.\n```go\nkeys, err := bt.LessThan([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n### LessThanEq\nTo get all keys less than or equal to the key you can use the ``LessThanEq`` method.\n```go\nkeys, err := bt.LessThanEq([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n### Deleting a key\n\nTo delete a key and all of it's values you can use the ``Delete`` method.\n```go\nerr := bt.Delete([]byte(\"key\"))\nif err != nil {\n..\n}\n```\n\n### Removing a value within key\n\nTo remove a value from a key you can use the ``Remove`` method.\n```go\nerr := bt.Remove([]byte(\"key\"), []byte(\"value\"))\nif err != nil {\n..\n}\n```\n\n### Key Iterator\n\nThe iterator is used to iterate over values of a key\n\n```go\niterator := key.Iterator()\n\nfor {\n    value, ok := iterator()\n    if !ok {\n        break\n    }\n\n    fmt.Println(string(value))\n}\n```\n\nResult\n```\nvalue1\nvalue2\nvalue3\n```\n\n### Range query\nGet all keys between key1 and key3\n```go\nkeys, err := bt.Range([]byte(\"key1\"), []byte(\"key3\"))\nif err != nil {\n..\n}\n```\n\n### Not Range query\nGet all keys not between key1 and key3\n```go\nkeys, err := bt.NRange([]byte(\"key1\"), []byte(\"key3\"))\nif err != nil {\n..\n}\n```\n\n### Closing the BTree\n\nYou can close the BTree by calling the Close function.\nThis will close the underlying file and free up resources.\n```go\nerr := bt.Close()\nif err != nil {\n..\n}\n```\n\n## Technical Details\nThis is an on disk btree implementation.  This btree has an underlying pager that handles reading and writing nodes to disk as well as overflows.\nWhen an overflow is required for a page the overflow is created and the data is split between however many pages.\nWhen a page gets deleted its page number gets placed into an in-memory slice as well as gets written to disk. These deleted pages are reused when new pages are needed.\n\nA key on this btree can store many values.  Mind you a keys values are read into memory; So if you have a key like A with values Alex, Alice, Adam, and you call Get(A) all of those values will be read into memory.\nYou can use a key iterator to iterate over the values of a key.\n\nThe btree is not thread safe.  You must handle concurrency control yourself.\n\nYou can play with page size and degree(T) to see how it affects performance.  My recommendation is a smaller page size and smaller degree for faster reads and writes.\n\n## License\nView the [LICENSE](LICENSE) file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguycipher%2Fbtree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguycipher%2Fbtree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguycipher%2Fbtree/lists"}