Hierarchical Partitioning

src/Microsoft.Azure.CosmosEventSourcing/Items/EventItem.cs

@@ -60,6 +60,11 @@ public DomainEvent DomainEvent
     /// </summary>
     public string PartitionKey { get; set; } = null!;
 
+    /// <summary>
+    /// The values used to partition the event.
+    /// </summary>
+    public IEnumerable<string> PartitionKeys { get; set; } = null!;
+
     /// <summary>
     /// The name of the event stored.
     /// </summary>

src/Microsoft.Azure.CosmosEventSourcing/Microsoft.Azure.CosmosEventSourcing.csproj

@@ -27,7 +27,7 @@
     <IncludeSymbols>false</IncludeSymbols>
     <IncludeSource>false</IncludeSource>
     <RootNamespace>Microsoft.Azure.CosmosEventSourcing</RootNamespace>
-    <NoWarn>NU5125</NoWarn>
+    <NoWarn>NU5125;NU1507</NoWarn>
     <Optimize Condition="'$(Configuration)'=='Release'">true</Optimize>
     <RepositoryUrl>https://github.com/IEvangelist/azure-cosmos-dotnet-repository</RepositoryUrl>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>

src/Microsoft.Azure.CosmosEventSourcing/Stores/DefaultEventStore.Read.cs

@@ -4,9 +4,9 @@
 using System.Linq.Expressions;
 using System.Reflection;
 using System.Runtime.CompilerServices;
+using Microsoft.Azure.Cosmos;
 using Microsoft.Azure.CosmosEventSourcing.Aggregates;
 using Microsoft.Azure.CosmosEventSourcing.Exceptions;
-using Microsoft.Azure.CosmosEventSourcing.Extensions;
 using Microsoft.Azure.CosmosRepository.Paging;
 
 namespace Microsoft.Azure.CosmosEventSourcing.Stores;
@@ -15,8 +15,7 @@ internal partial class DefaultEventStore<TEventItem>
 {
     public ValueTask<IEnumerable<TEventItem>> ReadAsync(string partitionKey,
         CancellationToken cancellationToken = default) =>
-        readOnlyRepository.GetAsync(
-            x => x.PartitionKey == partitionKey,
+        readOnlyRepository.GetAsync(new PartitionKey(partitionKey),
             cancellationToken);
 
     public async ValueTask<TAggregateRoot> ReadAggregateAsync<TAggregateRoot>(
@@ -25,7 +24,7 @@ public async ValueTask<TAggregateRoot> ReadAggregateAsync<TAggregateRoot>(
         where TAggregateRoot : IAggregateRoot
     {
         IEnumerable<TEventItem> events = await readOnlyRepository.GetAsync(
-            x => x.PartitionKey == partitionKey,
+            new PartitionKey(partitionKey),
             cancellationToken);
 
         var payloads = events
@@ -46,7 +45,7 @@ public async ValueTask<TAggregateRoot> ReadAggregateAsync<TAggregateRoot>(
         CancellationToken cancellationToken = default) where TAggregateRoot : IAggregateRoot
     {
         IEnumerable<TEventItem> events = await readOnlyRepository.GetAsync(
-            x => x.PartitionKey == partitionKey,
+            new PartitionKey(partitionKey),
             cancellationToken);
 
         return rootMapper.MapTo(events);
@@ -57,9 +56,8 @@ public ValueTask<IEnumerable<TEventItem>> ReadAsync(
         Expression<Func<TEventItem, bool>> predicate,
         CancellationToken cancellationToken = default) =>
         readOnlyRepository.GetAsync(
-            predicate.Compose(
-                x => x.PartitionKey == partitionKey,
-                Expression.AndAlso),
+            new PartitionKey(partitionKey),
+            predicate,
             cancellationToken);
 
     public async IAsyncEnumerable<TEventItem> StreamAsync(
@@ -69,13 +67,11 @@ public async IAsyncEnumerable<TEventItem> StreamAsync(
     {
         string? token = null;
 
-        Expression<Func<TEventItem, bool>> expression = eventSource =>
-            eventSource.PartitionKey == partitionKey;
-
         do
         {
             IPage<TEventItem> page = await readOnlyRepository.PageAsync(
-                expression,
+                new PartitionKey(partitionKey),
+                predicate: null,
                 chunkSize,
                 token,
                 cancellationToken: cancellationToken);

src/Microsoft.Azure.CosmosRepository.AspNetCore/Microsoft.Azure.CosmosRepository.AspNetCore.csproj

@@ -31,7 +31,7 @@
         <IncludeSymbols>false</IncludeSymbols>
         <IncludeSource>false</IncludeSource>
         <RootNamespace>Microsoft.Azure.CosmosRepository.AspNetCore</RootNamespace>
-        <NoWarn>NU5125</NoWarn>
+        <NoWarn>NU5125;NU1507</NoWarn>
         <Optimize Condition="'$(Configuration)'=='Release'">true</Optimize>
         <RepositoryUrl>https://github.com/IEvangelist/azure-cosmos-dotnet-repository</RepositoryUrl>
         <PackageLicenseFile>LICENSE</PackageLicenseFile>

src/Microsoft.Azure.CosmosRepository/Attributes/PartitionKeyPathAttribute.cs

@@ -9,20 +9,22 @@ namespace Microsoft.Azure.CosmosRepository.Attributes;
 /// conjunction with a <see cref="Newtonsoft.Json.JsonPropertyAttribute"/> on the <see cref="IItem"/> property
 /// whose value will act as the partition key. Partition key paths should start with "/",
 /// for example "/partition". For more information,
-/// see https://docs.microsoft.com/azure/cosmos-db/partitioning-overview.
+/// see https://docs.microsoft.com/azure/cosmos-db/partitioning-overview and
+/// https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys
 /// </summary>
 /// <remarks>
 /// By default, "/id" is used.
 /// </remarks>
 /// <remarks>
-/// Constructor accepting the <paramref name="path"/> of the partition key for a given <see cref="IItem"/>.
+/// Constructor accepting the <paramref name="paths"/> of the partition keys for a given <see cref="IItem"/>.
 /// </remarks>
-/// <param name="path"></param>
+/// <param name="paths"></param>
 [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
-public sealed class PartitionKeyPathAttribute(string path) : Attribute
+public sealed class PartitionKeyPathAttribute(params string[] paths) : Attribute
 {
     /// <summary>
-    /// Gets the path of the parition key.
+    /// Gets the path values of the parition key.
     /// </summary>
-    public string Path { get; } = path ?? throw new ArgumentNullException(nameof(path), "A path is required.");
+    public string[] Paths { get; } = paths != null && paths.Length >= 1 ? paths : throw new ArgumentNullException(nameof(paths), "At least one path is required.");
 }
+

src/Microsoft.Azure.CosmosRepository/Builders/ContainerOptionsBuilder.cs

@@ -23,9 +23,9 @@ public class ContainerOptionsBuilder(Type type)
     internal string? Name { get; private set; }
 
     /// <summary>
-    /// The partition key for the container.
+    /// The partition keys for the container.
     /// </summary>
-    internal string? PartitionKey { get; private set; }
+    internal IList<string>? PartitionKeys { get; private set; }
 
     /// <summary>
     /// The default time to live for a container.
@@ -79,7 +79,11 @@ public ContainerOptionsBuilder WithContainer(string name)
     /// <exception cref="ArgumentNullException"></exception>
     public ContainerOptionsBuilder WithPartitionKey(string partitionKey)
     {
-        PartitionKey = partitionKey ?? throw new ArgumentNullException(nameof(partitionKey));
+        if (partitionKey is null) throw new ArgumentNullException(nameof(partitionKey));
+
+        PartitionKeys ??= [];
+        PartitionKeys.Add(partitionKey);
+
         return this;
     }
 

src/Microsoft.Azure.CosmosRepository/IItem.cs

@@ -18,8 +18,13 @@ public interface IItem
     /// </summary>
     string Type { get; set; }
 
+    ///// <summary>
+    ///// Gets the item's PartitionKey. This string is used to instantiate the <c>Cosmos.PartitionKey</c> struct.
+    ///// </summary>
+    string PartitionKey { get; }
+
     /// <summary>
-    /// Gets the item's PartitionKey. This string is used to instantiate the <c>Cosmos.PartitionKey</c> struct.
+    /// Gets the item PartitionKeys. This string array is used to instantiate the <c>Cosmos.PartitionKeys</c> struct.
     /// </summary>
-    string PartitionKey { get; }
+    IEnumerable<string> PartitionKeys { get; }
 }

src/Microsoft.Azure.CosmosRepository/Item.cs

@@ -44,10 +44,16 @@ public abstract class Item : IItem
     public string Type { get; set; }
 
     /// <summary>
-    /// Gets the PartitionKey based on <see cref="GetPartitionKeyValue"/>.
+    /// Gets the PartitionKey based on <see cref="GetPartitionKeyValues"/> last record.
     /// Implemented explicitly to keep out of Item API
     /// </summary>
-    string IItem.PartitionKey => GetPartitionKeyValue();
+    string IItem.PartitionKey => GetPartitionKeyValues().Last();
+
+    /// <summary>
+    /// Gets the PartitionKeys based on <see cref="GetPartitionKeyValues"/>.
+    /// Implemented explicitly to keep out of Item API
+    /// </summary>
+    IEnumerable<string> IItem.PartitionKeys => GetPartitionKeyValues();
 
     /// <summary>
     /// Default constructor, assigns type name to <see cref="Type"/> property.
@@ -56,10 +62,20 @@ public abstract class Item : IItem
 
     /// <summary>
     /// Gets the partition key value for the given <see cref="Item"/> type.
-    /// When overridden, be sure that the <see cref="PartitionKeyPathAttribute.Path"/> value corresponds
-    /// to the <see cref="JsonPropertyAttribute.PropertyName"/> value, i.e.; "/partition" and "partition"
+    /// When overridden, be sure that the <see cref="PartitionKeyPathAttribute.Paths"/> values correspond
+    /// to the <see cref="JsonPropertyAttribute.PropertyName"/> values, i.e.; "/partition" and "partition"
     /// respectively. If these two values do not correspond an error will occur.
     /// </summary>
     /// <returns>The <see cref="Item.Id"/> unless overridden by the subclass.</returns>
     protected virtual string GetPartitionKeyValue() => Id;
+
+    /// <summary>
+    /// Gets the partition key values for the given <see cref="Item"/> type.
+    /// When overridden, be sure that the <see cref="PartitionKeyPathAttribute.Paths"/> values correspond
+    /// to the <see cref="JsonPropertyAttribute.PropertyName"/> values, i.e.; "/partition" and "partition"
+    /// respectively. If all provided key values do not have a matching property with the equivalent name, an error will occur.
+    /// Make sure to add the latest inner 
+    /// </summary>
+    /// <returns>The list with <see cref="Item.Id"/> unless overridden by the subclass.</returns>
+    protected virtual IEnumerable<string> GetPartitionKeyValues() => new string[] { GetPartitionKeyValue() };
 }

src/Microsoft.Azure.CosmosRepository/Logging/LoggerExtensions.cs

@@ -19,6 +19,13 @@ public static void LogPointReadStarted<TItem>(
         string partitionKey) where TItem : IItem =>
         LoggerMessageDefinitions.PointReadStarted(logger, typeof(TItem).Name, id, partitionKey, null!);
 
+    //Info Logger Extensions
+    public static void LogPointReadStarted<TItem>(
+        this ILogger logger,
+        string id,
+        IEnumerable<string> partitionKeys) where TItem : IItem =>
+        LoggerMessageDefinitions.HierarchicalPointReadStarted(logger, typeof(TItem).Name, id, partitionKeys, null!);
+
     public static void LogPointReadExecuted<TItem>(
         this ILogger logger,
         double ruCharge) where TItem : IItem =>
@@ -41,4 +48,11 @@ public static void LogItemNotFoundHandled<TItem>(
         string partitionKey,
         CosmosException e) where TItem : IItem =>
         LoggerMessageDefinitions.ItemNotFoundHandled(logger, typeof(TItem).Name, id, partitionKey, e);
+
+    public static void LogItemNotFoundHandled<TItem>(
+        this ILogger logger,
+        string id,
+        IEnumerable<string> partitionKeys,
+        CosmosException e) where TItem : IItem =>
+        LoggerMessageDefinitions.HierarchicalItemNotFoundHandled(logger, typeof(TItem).Name, id, partitionKeys, e);
 }

src/Microsoft.Azure.CosmosRepository/Logging/LoggerMessageDefinitions.cs

@@ -20,6 +20,14 @@ internal static class LoggerMessageDefinitions
             "Point read started for item type {CosmosItemType} with id {CosmosItemId} and partitionKey {CosmosItemPartitionKey}"
         );
 
+    // Info Definitions
+    internal static readonly Action<ILogger, string, string, IEnumerable<string>, Exception?> HierarchicalPointReadStarted =
+        LoggerMessage.Define<string, string, IEnumerable<string>>(
+            LogLevel.Information,
+            EventIds.CosmosPointReadStarted,
+            "Point read started for item type {CosmosItemType} with id {CosmosItemId} and partitionKeys {CosmosItemPartitionKeys}"
+        );
+
     internal static readonly Action<ILogger, string, double, Exception?> PointReadExecuted =
         LoggerMessage.Define<string, double>(
             LogLevel.Information,
@@ -46,4 +54,11 @@ internal static class LoggerMessageDefinitions
             EventIds.ItemNotFoundHandled,
             "CosmosException Status Code 404 handled for item of type {CosmosItemType} with {CosmosItemId} and partition key {CosmosItemPartitionKey}"
         );
+
+    internal static readonly Action<ILogger, string, string, IEnumerable<string>, Exception?> HierarchicalItemNotFoundHandled =
+        LoggerMessage.Define<string, string, IEnumerable<string>>(
+            LogLevel.Information,
+            EventIds.ItemNotFoundHandled,
+            "CosmosException Status Code 404 handled for item of type {CosmosItemType} with {CosmosItemId} and partition keys {CosmosItemPartitionKeys}"
+        );
 }

src/Microsoft.Azure.CosmosRepository/Microsoft.Azure.CosmosRepository.csproj

@@ -34,7 +34,7 @@
         <IncludeSymbols>false</IncludeSymbols>
         <IncludeSource>false</IncludeSource>
         <RootNamespace>Microsoft.Azure.CosmosRepository</RootNamespace>
-        <NoWarn>NU5125</NoWarn>
+        <NoWarn>NU5125;NU1507</NoWarn>
         <Optimize Condition="'$(Configuration)'=='Release'">true</Optimize>
         <RepositoryUrl>https://github.com/IEvangelist/azure-cosmos-dotnet-repository</RepositoryUrl>
         <PackageLicenseFile>LICENSE</PackageLicenseFile>

src/Microsoft.Azure.CosmosRepository/Options/ItemConfiguration.cs

@@ -3,32 +3,59 @@
 
 namespace Microsoft.Azure.CosmosRepository.Options;
 
-internal class ItemConfiguration(
-    Type type,
-    string containerName,
-    string partitionKeyPath,
-    UniqueKeyPolicy? uniqueKeyPolicy,
-    ThroughputProperties? throughputProperties,
-    int defaultTimeToLive = -1,
-    bool syncContainerProperties = false,
-    ChangeFeedOptions? changeFeedOptions = null,
-    bool useStrictTypeChecking = true)
+internal class ItemConfiguration
 {
-    public Type Type { get; } = type;
-
-    public string ContainerName { get; } = containerName;
-
-    public string PartitionKeyPath { get; } = partitionKeyPath;
-
-    public UniqueKeyPolicy? UniqueKeyPolicy { get; } = uniqueKeyPolicy;
-
-    public ThroughputProperties? ThroughputProperties { get; } = throughputProperties;
-
-    public int DefaultTimeToLive { get; } = defaultTimeToLive;
-
-    public bool SyncContainerProperties { get; } = syncContainerProperties;
-
-    public ChangeFeedOptions? ChangeFeedOptions { get; } = changeFeedOptions;
-
-    public bool UseStrictTypeChecking { get; } = useStrictTypeChecking;
-}
+    public ItemConfiguration(
+        Type type,
+        string containerName,
+        string partitionKeyPath,
+        UniqueKeyPolicy? uniqueKeyPolicy = null,
+        ThroughputProperties? throughputProperties = null,
+        int defaultTimeToLive = -1,
+        bool syncContainerProperties = false,
+        ChangeFeedOptions? changeFeedOptions = null,
+        bool useStrictTypeChecking = true)
+        : this(type, containerName, new[] { partitionKeyPath }, uniqueKeyPolicy, throughputProperties, defaultTimeToLive, syncContainerProperties, changeFeedOptions, useStrictTypeChecking)
+    {
+    }
+
+    public ItemConfiguration(
+        Type type,
+        string containerName,
+        IEnumerable<string> partitionKeyPaths,
+        UniqueKeyPolicy? uniqueKeyPolicy = null,
+        ThroughputProperties? throughputProperties = null,
+        int defaultTimeToLive = -1,
+        bool syncContainerProperties = false,
+        ChangeFeedOptions? changeFeedOptions = null,
+        bool useStrictTypeChecking = true)
+    {
+        Type = type;
+        ContainerName = containerName;
+        PartitionKeyPaths = partitionKeyPaths;
+        UniqueKeyPolicy = uniqueKeyPolicy;
+        ThroughputProperties = throughputProperties;
+        DefaultTimeToLive = defaultTimeToLive;
+        SyncContainerProperties = syncContainerProperties;
+        ChangeFeedOptions = changeFeedOptions;
+        UseStrictTypeChecking = useStrictTypeChecking;
+    }
+
+    public Type Type { get; }
+
+    public string ContainerName { get; }
+
+    public IEnumerable<string> PartitionKeyPaths { get; }
+
+    public UniqueKeyPolicy? UniqueKeyPolicy { get; }
+
+    public ThroughputProperties? ThroughputProperties { get; }
+
+    public int DefaultTimeToLive { get; }
+
+    public bool SyncContainerProperties { get; }
+
+    public ChangeFeedOptions? ChangeFeedOptions { get; }
+
+    public bool UseStrictTypeChecking { get; }
+}

src/Microsoft.Azure.CosmosRepository/Providers/DefaultCosmosItemConfigurationProvider.cs

@@ -39,7 +39,7 @@ private ItemConfiguration AddOptions(Type itemType)
         itemType.IsItem();
 
         var containerName = containerNameProvider.GetContainerName(itemType);
-        var partitionKeyPath = cosmosPartitionKeyPathProvider.GetPartitionKeyPath(itemType);
+        var partitionKeyPaths = cosmosPartitionKeyPathProvider.GetPartitionKeyPaths(itemType);
         UniqueKeyPolicy? uniqueKeyPolicy = cosmosUniqueKeyPolicyProvider.GetUniqueKeyPolicy(itemType);
         var timeToLive = containerDefaultTimeToLiveProvider.GetDefaultTimeToLive(itemType);
         var sync = syncContainerPropertiesProvider.GetWhetherToSyncContainerProperties(itemType);
@@ -49,11 +49,12 @@ private ItemConfiguration AddOptions(Type itemType)
         return new(
             itemType,
             containerName,
-            partitionKeyPath,
+            partitionKeyPaths,
             uniqueKeyPolicy,
             throughputProperties,
             timeToLive,
             sync,
             useStrictTypeChecking: useStrictTypeChecking);
+
     }
 }