https://github.com/sergiyseletsky/unified
Unified Id - the identity of your data.
https://github.com/sergiyseletsky/unified
azure cosmosdb dotnet dotnet-core dotnet-standard partitioning sharding storage storage-abstractions
Last synced: 5 months ago
JSON representation
Unified Id - the identity of your data.
- Host: GitHub
- URL: https://github.com/sergiyseletsky/unified
- Owner: SergiySeletsky
- License: mit
- Created: 2018-04-05T05:48:41.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-07-09T21:28:47.000Z (almost 2 years ago)
- Last Synced: 2025-11-27T19:56:19.147Z (6 months ago)
- Topics: azure, cosmosdb, dotnet, dotnet-core, dotnet-standard, partitioning, sharding, storage, storage-abstractions
- Language: C#
- Homepage: https://github.com/SergiySeletsky/Unified
- Size: 453 KB
- Stars: 40
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# **Unified Id** - the identity of your data.
[](https://github.com/SergiySeletsky/Unified/compare)
[](https://github.com/SergiySeletsky/Unified/actions?query=workflow:Build)
[](https://sonarcloud.io/dashboard?id=Unified)
[](https://www.nuget.org/packages/Unified)
## Why
What is Unified Id?
If 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.
What are the main advantages?
| Feature | Unified | GUID |
| ------ | ------ | ------ |
| Size | 8 byte (13 as string) | 16 byte (36 as string)
| Partitioning | Build-in | No, external can be added
| Collisions | 0.00000001% in 10B IDs | 50% in 2.7e18 IDs
| Cast | implicit(string, ulong, long) | explicit(byte[], Parse/ToString)
| Generate | Build-in(byte[], string, GUID) | No, only random NewGuid
| Null/Empty-handling | Friendly as Empty | Exception
## Getting started
Install the [NuGet package](https://www.nuget.org/packages/Unified) and write the following code:
```c#
using Unified;
class Program
{
static void Main()
{
var id = UnifiedId.NewId(); // AFHUTVDSGUGVQ
}
}
```
You have created your first Unified Id!
Want to use it as a string? `string id = UnifiedId.NewId();` or long? `long id = UnifiedId.NewId();`
UnifiedId could be used as DDD ValueObject in your entities.
```c#
using Unified;
class User
{
public UnifiedId UserId { set; get; }
}
class Program
{
static void Main()
{
var user = new User
{
UserId = UnifiedId.NewId();
};
var settings = new JsonSerializerSettings // Could be added to global settings.
{
Converters = new List
{
new UnifiedIdConverter()
}
};
var json = JsonConvert.SerializeObject(user, settings); // { "UserId": "AFHUTVDSGUGVQ" }
}
}
```
## How it works
```c#
using Unified;
class Program
{
static void Main()
{
var guid = Guid.NewGuid();
var id = UnifiedId.FromGuid(guid);
var fnv = id.ToUInt64();
Console.WriteLine($"{guid} => {fnv} => {id}");
// 8dd02ad1-62cc-4015-9502-49658ba240ae => 15834445116674749764 => DNFPVU1LD2DA4
}
}
```
Unified Id generates 64bit FNV-1a Id's based on GUID and converts it to HEX32 to use as string.
HEX32 is reversible, so you can convert it back from string to UInt64.
`ulong number = UnifiedId.Parse("DNFPVU1LD2DA4");`
Why FNV-1a 64bit? because it has the best space randomization in the case of GUID conversion, below is space representation.
Default method of generation is GUID based using method `var id = UnifiedId.NewId();`.
This value could be used as string converted in HEX32 consisting of two parts.
[KEY][UNIFIED_ID] KEY - Partition/Shard Key and UNIFIED_ID as Row Unified Key together used as the global identity.
You can also generate this Id as a one-way hash using the following sources:
* `UnifiedId FromGuid(Guid id)`
* `UnifiedId FromBytes(byte[] bytes)`
* `UnifiedId FromString(string text)`
* `UnifiedId FromInt64(long number)`
* `UnifiedId FromUInt64(ulong number)`
Do you need sequential Id? `var id = new UnifiedId(DateTime.UtcNow.Ticks)`
Want to save partitioned data? It's easy...
```c#
using Unified;
using System;
class Program
{
static void Main()
{
// Let's emulate the partitioned database.
var db = new Dictionary>();
// We will use 10M records, just to execute it fast.
var all = 10000000;
for (var i = 0; i <= all; i++)
{
// Generate random Id.
var id = UnifiedId.NewId();
// Get it's partition key. Number of partitions could be customized, default 16K.
var partition = id.PartitionKey();
// Initialize partitions in your DB.
if (!db.ContainsKey(partition))
{
db.Add(partition, new List());
}
// Add values to partitions.
db[partition].Add(id);
}
}
}
```
Result:
```
DB Count : 16384
Each item contain : 610 elements +/-5%
```
We recommend using Unified Id for data sets size up to 10 billion Ids. More will increase the chance of collision.
© 2021 Serhii Seletskyi. All rights reserved.