{"id":37033163,"url":"https://github.com/sergiyseletsky/unified","last_synced_at":"2026-01-14T04:00:32.383Z","repository":{"id":45935880,"uuid":"128164514","full_name":"SergiySeletsky/Unified","owner":"SergiySeletsky","description":"Unified Id - the identity of your data.","archived":false,"fork":false,"pushed_at":"2024-07-09T21:28:47.000Z","size":464,"stargazers_count":40,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-27T19:56:19.147Z","etag":null,"topics":["azure","cosmosdb","dotnet","dotnet-core","dotnet-standard","partitioning","sharding","storage","storage-abstractions"],"latest_commit_sha":null,"homepage":"https://github.com/SergiySeletsky/Unified","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SergiySeletsky.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":"2018-04-05T05:48:41.000Z","updated_at":"2025-09-30T14:19:24.000Z","dependencies_parsed_at":"2024-06-18T20:07:44.300Z","dependency_job_id":"6610d37e-56e9-4f3d-9f81-5a7808793c8c","html_url":"https://github.com/SergiySeletsky/Unified","commit_stats":{"total_commits":69,"total_committers":1,"mean_commits":69.0,"dds":0.0,"last_synced_commit":"d0603fa8d688fca1ff63c090f022c35017f1747e"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SergiySeletsky/Unified","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SergiySeletsky%2FUnified","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SergiySeletsky%2FUnified/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SergiySeletsky%2FUnified/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SergiySeletsky%2FUnified/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SergiySeletsky","download_url":"https://codeload.github.com/SergiySeletsky/Unified/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SergiySeletsky%2FUnified/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["azure","cosmosdb","dotnet","dotnet-core","dotnet-standard","partitioning","sharding","storage","storage-abstractions"],"created_at":"2026-01-14T04:00:19.968Z","updated_at":"2026-01-14T04:00:32.370Z","avatar_url":"https://github.com/SergiySeletsky.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Unified Id** - the identity of your data.\n\n[![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](https://github.com/SergiySeletsky/Unified/compare)\n[![Build](https://github.com/SergiySeletsky/Unified/workflows/Build/badge.svg)](https://github.com/SergiySeletsky/Unified/actions?query=workflow:Build)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Unified\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=Unified)\n[![NuGet](https://img.shields.io/nuget/v/Unified)](https://www.nuget.org/packages/Unified)\n\n## Why\n\nWhat is Unified Id?\nIf GUID is too heavy for your application but you need a random global Id that can be used as a string or long basic type, you are in right place.\n\nWhat are the main advantages?\n\n| Feature | Unified | GUID |\n| ------ | ------ | ------ |\n| Size | 8 byte (13 as string) | 16 byte (36 as string)\n| Partitioning | Build-in | No, external can be added\n| Collisions | 0.00000001% in 10B IDs | 50% in 2.7e18 IDs\n| Cast | implicit(string, ulong, long) | explicit(byte[], Parse/ToString)\n| Generate | Build-in(byte[], string, GUID) | No, only random NewGuid\n| Null/Empty-handling | Friendly as Empty | Exception\n\n## Getting started\n\nInstall the [NuGet package](https://www.nuget.org/packages/Unified) and write the following code:\n\n```c#\nusing Unified;\n\nclass Program\n{\n    static void Main()\n    {\n        var id = UnifiedId.NewId(); // AFHUTVDSGUGVQ\n    }\n}\n```\n\nYou have created your first Unified Id!\n\nWant to use it as a string? `string id = UnifiedId.NewId();` or long? `long id = UnifiedId.NewId();`\n\nUnifiedId could be used as DDD ValueObject in your entities.\n\n```c#\nusing Unified;\n\nclass User\n{\n    public UnifiedId UserId { set; get; }\n}\n\nclass Program\n{\n    static void Main()\n    {\n        var user = new User\n        {\n            UserId = UnifiedId.NewId();\n        };\n\n        var settings = new JsonSerializerSettings // Could be added to global settings.\n        { \n            Converters = new List\u003cJsonConverter\u003e \n            { \n                new UnifiedIdConverter() \n            }\n        };\n        var json = JsonConvert.SerializeObject(user, settings); // { \"UserId\": \"AFHUTVDSGUGVQ\" }\n    }\n}\n```\n\n## How it works\n\n```c#\nusing Unified;\n\nclass Program\n{\n    static void Main()\n    {\n        var guid = Guid.NewGuid();\n        var id = UnifiedId.FromGuid(guid);\n        var fnv = id.ToUInt64();\n        Console.WriteLine($\"{guid} =\u003e {fnv} =\u003e {id}\");\n        // 8dd02ad1-62cc-4015-9502-49658ba240ae =\u003e 15834445116674749764 =\u003e DNFPVU1LD2DA4\n    }\n}\n```\n\nUnified Id generates 64bit FNV-1a Id's based on GUID and converts it to HEX32 to use as string.\n\n![Algorithm](https://raw.githubusercontent.com/SergiySeletsky/Unified/master/docs/algorithm.png)\n\nHEX32 is reversible, so you can convert it back from string to UInt64.\n`ulong number = UnifiedId.Parse(\"DNFPVU1LD2DA4\");`\n\nWhy FNV-1a 64bit? because it has the best space randomization in the case of GUID conversion, below is space representation.\n\n![FNV-1a](https://raw.githubusercontent.com/SergiySeletsky/Unified/master/docs/fnv-1a-space.png)\n\nDefault method of generation is GUID based using method `var id = UnifiedId.NewId();`.\n\nThis value could be used as string converted in HEX32 consisting of two parts.\n\n[KEY][UNIFIED_ID] KEY - Partition/Shard Key and UNIFIED_ID as Row Unified Key together used as the global identity.\n\nYou can also generate this Id as a one-way hash using the following sources:\n\n* `UnifiedId FromGuid(Guid id)`\n* `UnifiedId FromBytes(byte[] bytes)`\n* `UnifiedId FromString(string text)`\n* `UnifiedId FromInt64(long number)`\n* `UnifiedId FromUInt64(ulong number)`\n\nDo you need sequential Id? `var id = new UnifiedId(DateTime.UtcNow.Ticks)`\n\nWant to save partitioned data? It's easy...\n\n```c#\nusing Unified;\nusing System;\n\nclass Program\n{\n    static void Main()\n    {\n        // Let's emulate the partitioned database.\n        var db = new Dictionary\u003cstring, List\u003cUnifiedId\u003e\u003e();\n\n        // We will use 10M records, just to execute it fast.\n        var all = 10000000; \n        for (var i = 0; i \u003c= all; i++)\n        {\n            // Generate random Id.\n            var id = UnifiedId.NewId();\n\n            // Get it's partition key. Number of partitions could be customized, default 16K.\n            var partition = id.PartitionKey();\n\n            // Initialize partitions in your DB.\n            if (!db.ContainsKey(partition))\n            {\n                db.Add(partition, new List\u003cUnifiedId\u003e());\n            }\n\n            // Add values to partitions.\n            db[partition].Add(id);\n        }\n    }\n}\n```\n\nResult:\n```\nDB Count             : 16384\nEach item contain    : 610 elements +/-5%\n```\nWe recommend using Unified Id for data sets size up to 10 billion Ids. More will increase the chance of collision.\n\n\n\n© 2021 Serhii Seletskyi. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergiyseletsky%2Funified","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsergiyseletsky%2Funified","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergiyseletsky%2Funified/lists"}