/azure-docs-sdk-dotnet

Permalink
Switch branches/tags
Nothing to show
Find file
azure-docs-sdk-dotnet/xml/Microsoft.Azure.Documents.Partitioning/HashPartitionResolver.xml
Fetching contributors…
Cannot retrieve contributors at this time
Raw Blame History
358 lines (358 sloc) 21.3 KB
<Type Name="HashPartitionResolver" FullName="Microsoft.Azure.Documents.Partitioning.HashPartitionResolver">
<TypeSignature Language="C#" Value="public class HashPartitionResolver : IDisposable, Microsoft.Azure.Documents.Client.IPartitionResolver" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit HashPartitionResolver extends System.Object implements class Microsoft.Azure.Documents.Client.IPartitionResolver, class System.IDisposable" />
<TypeSignature Language="DocId" Value="T:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver" />
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<Base>
<BaseTypeName>System.Object</BaseTypeName>
</Base>
<Interfaces>
<Interface>
<InterfaceName>Microsoft.Azure.Documents.Client.IPartitionResolver</InterfaceName>
</Interface>
<Interface>
<InterfaceName>System.IDisposable</InterfaceName>
</Interface>
</Interfaces>
<Attributes>
<Attribute>
<AttributeName>System.Obsolete("Support for IPartitionResolver based classes is now obsolete. It's recommended that you use partitioned collections for higher storage and throughput.")</AttributeName>
</Attribute>
</Attributes>
<Docs>
<summary>
HashPartitionResolver implements partitioning based on the value of a hash function, allowing you to evenly
distribute requests and data across a number of partitions in the Azure DocumentDB database service.
</summary>
<remarks>
<para>
Support for IPartitionResolver based classes is now obsolete. It's recommended that you use
<a href="https://azure.microsoft.com/documentation/articles/documentdb-partition-data">Partitioned Collections</a> for higher storage and throughput.
</para>
<para>
The HashPartitionResolver class internally implements a consistent hash ring over the hash function specified in the
<see cref="T:Microsoft.Azure.Documents.Partitioning.IHashGenerator" /> interface. By default, the HashPartitionResolver provides an MD5 hash function, but this can be
swapped out with a different hashing implementation. The consistent hash ring creates 16 replicas for each collection in order
to achieve a more uniform distribution of documents across collections.
</para>
<para>
The hash partitioning is most suitable for partitioning when the partition key has a high cardinality because it will distribute
the data evenly across collections. Typically hash partitioning uses the id property. A common use cases for hash partitioning is data
produced or consumed from a large number of distinct clients or for storing user profiles, catalog items, and telemetry data.
</para>
</remarks>
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public HashPartitionResolver (Func&lt;object,string&gt; partitionKeyExtractor, System.Collections.Generic.IEnumerable&lt;string&gt; collectionLinks, int numberOfVirtualNodesPerCollection = 128, Microsoft.Azure.Documents.Partitioning.IHashGenerator hashGenerator = null);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(class System.Func`2&lt;object, string&gt; partitionKeyExtractor, class System.Collections.Generic.IEnumerable`1&lt;string&gt; collectionLinks, int32 numberOfVirtualNodesPerCollection, class Microsoft.Azure.Documents.Partitioning.IHashGenerator hashGenerator) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.#ctor(System.Func{System.Object,System.String},System.Collections.Generic.IEnumerable{System.String},System.Int32,Microsoft.Azure.Documents.Partitioning.IHashGenerator)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="partitionKeyExtractor" Type="System.Func&lt;System.Object,System.String&gt;" />
<Parameter Name="collectionLinks" Type="System.Collections.Generic.IEnumerable&lt;System.String&gt;" />
<Parameter Name="numberOfVirtualNodesPerCollection" Type="System.Int32" />
<Parameter Name="hashGenerator" Type="Microsoft.Azure.Documents.Partitioning.IHashGenerator" />
</Parameters>
<Docs>
<param name="partitionKeyExtractor">A function to extract the partitionKey from the document</param>
<param name="collectionLinks">The list of collection links used for hashing.</param>
<param name="numberOfVirtualNodesPerCollection">The number of virtual nodes per collection in the conisistent hash ring.</param>
<param name="hashGenerator">The <see cref="T:Microsoft.Azure.Documents.Partitioning.IHashGenerator" /> to use in consistent hashing. If null, the default MD5 hash generator is used.</param>
<summary>
Initializes a new instance of the <see cref="T:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver" /> in the Azure DocumentDB database service using the specified <paramref name="partitionKeyExtractor" /> value.
</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public HashPartitionResolver (string partitionKeyPropertyName, System.Collections.Generic.IEnumerable&lt;string&gt; collectionLinks, int numberOfVirtualNodesPerCollection = 128, Microsoft.Azure.Documents.Partitioning.IHashGenerator hashGenerator = null);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string partitionKeyPropertyName, class System.Collections.Generic.IEnumerable`1&lt;string&gt; collectionLinks, int32 numberOfVirtualNodesPerCollection, class Microsoft.Azure.Documents.Partitioning.IHashGenerator hashGenerator) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.#ctor(System.String,System.Collections.Generic.IEnumerable{System.String},System.Int32,Microsoft.Azure.Documents.Partitioning.IHashGenerator)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="partitionKeyPropertyName" Type="System.String" />
<Parameter Name="collectionLinks" Type="System.Collections.Generic.IEnumerable&lt;System.String&gt;" />
<Parameter Name="numberOfVirtualNodesPerCollection" Type="System.Int32" />
<Parameter Name="hashGenerator" Type="Microsoft.Azure.Documents.Partitioning.IHashGenerator" />
</Parameters>
<Docs>
<param name="partitionKeyPropertyName">The name of the property in the document to execute the hashing on.</param>
<param name="collectionLinks">The list of collection links used for hashing.</param>
<param name="numberOfVirtualNodesPerCollection">The number of virtual nodes per collection in the conisistent hash ring.</param>
<param name="hashGenerator">The <see cref="T:Microsoft.Azure.Documents.Partitioning.IHashGenerator" /> to use in consistent hashing. If null, the default MD5 hash generator is used.</param>
<summary>
Initializes a new instance of the <see cref="T:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver" /> in the Azure DocumentDB database service using the specified <paramref name="partitionKeyPropertyName" /> value.
</summary>
<remarks>
Use when you want to partition based on a single property name. For other partitioning schemes, use the constructor
with partitionKeyExtractor instead.
</remarks>
</Docs>
</Member>
<Member MemberName="CollectionLinks">
<MemberSignature Language="C#" Value="public System.Collections.Generic.IEnumerable&lt;string&gt; CollectionLinks { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance class System.Collections.Generic.IEnumerable`1&lt;string&gt; CollectionLinks" />
<MemberSignature Language="DocId" Value="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.CollectionLinks" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>
Gets the IEnumerable of collection links used for hashing in the Azure DocumentDB database service.
</summary>
<value>The IEnumerable of collection links used for hashing.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Dispose">
<MemberSignature Language="C#" Value="public void Dispose ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Dispose() cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.Dispose" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>
Disposes the resolver in the Azure DocumentDB database service.
</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Finalize">
<MemberSignature Language="C#" Value="~HashPartitionResolver ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig virtual instance void Finalize() cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.Finalize" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>
Class destructor.
</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="GetPartitionKey">
<MemberSignature Language="C#" Value="public virtual object GetPartitionKey (object document);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance object GetPartitionKey(object document) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.GetPartitionKey(System.Object)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Object</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="document" Type="System.Object" />
</Parameters>
<Docs>
<param name="document">A document object</param>
<summary>
Extracts the partition key from the specified document using the specified <see cref="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.PartitionKeyPropertyName" />
property or <see cref="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.PartitionKeyExtractor" /> function in order of preference in the Azure DocumentDB database service.
</summary>
<returns>object used as the partition key.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">Thrown if unable to extract the partition key.</exception>
</Docs>
</Member>
<Member MemberName="HashGenerator">
<MemberSignature Language="C#" Value="public Microsoft.Azure.Documents.Partitioning.IHashGenerator HashGenerator { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance class Microsoft.Azure.Documents.Partitioning.IHashGenerator HashGenerator" />
<MemberSignature Language="DocId" Value="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.HashGenerator" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute>
<AttributeName>Newtonsoft.Json.JsonIgnore</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>Microsoft.Azure.Documents.Partitioning.IHashGenerator</ReturnType>
</ReturnValue>
<Docs>
<summary>
Gets the HashGenerator used in consistent hashing.
</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="NumberOfVirtualNodesPerCollection">
<MemberSignature Language="C#" Value="public int NumberOfVirtualNodesPerCollection { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance int32 NumberOfVirtualNodesPerCollection" />
<MemberSignature Language="DocId" Value="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.NumberOfVirtualNodesPerCollection" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>
The number of virtual nodes per collection in the conisistent hash ring in the Azure DocumentDB database service. This controls the compromise of skewness of documents accross collections vs the consistent hashing latency.
</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="PartitionKeyExtractor">
<MemberSignature Language="C#" Value="public Func&lt;object,string&gt; PartitionKeyExtractor { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance class System.Func`2&lt;object, string&gt; PartitionKeyExtractor" />
<MemberSignature Language="DocId" Value="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.PartitionKeyExtractor" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Func&lt;System.Object,System.String&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>
Gets the function to extract the partition key from an object in the Azure DocumentDB database service.
</summary>
<value>The function to extract the partition key from an object.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="PartitionKeyPropertyName">
<MemberSignature Language="C#" Value="public string PartitionKeyPropertyName { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance string PartitionKeyPropertyName" />
<MemberSignature Language="DocId" Value="P:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.PartitionKeyPropertyName" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>
Gets the name of the property in the document to execute the hashing on in the Azure DocumentDB database service.
</summary>
<value>The name of the property in the document to execute the hashing on.</value>
<remarks>
HashPartitionResolver supports two modes - one using PartitionKeyPropertyName and the other using PartitionKeyExtractor.
PartitionKeyPropertyName is extracted using Reflection, so use the C# property name, not the JSON representation.
</remarks>
</Docs>
</Member>
<Member MemberName="ResolveForCreate">
<MemberSignature Language="C#" Value="public virtual string ResolveForCreate (object partitionKey);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance string ResolveForCreate(object partitionKey) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.ResolveForCreate(System.Object)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="partitionKey" Type="System.Object" />
</Parameters>
<Docs>
<param name="partitionKey">The partition key used to determine the target collection for creates.</param>
<summary>
Given a partition key, returns the collection self-link for creating a document in the Azure DocumentDB database service.
</summary>
<returns>The target collection link that will be used for document creation.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">Thrown if the specified <paramref name="partitionKey" /> is null.</exception>
</Docs>
</Member>
<Member MemberName="ResolveForRead">
<MemberSignature Language="C#" Value="public virtual System.Collections.Generic.IEnumerable&lt;string&gt; ResolveForRead (object partitionKey);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance class System.Collections.Generic.IEnumerable`1&lt;string&gt; ResolveForRead(object partitionKey) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Azure.Documents.Partitioning.HashPartitionResolver.ResolveForRead(System.Object)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Azure.Documents.Client</AssemblyName>
<AssemblyVersion>1.14.0.0</AssemblyVersion>
<AssemblyVersion>1.16.0.0</AssemblyVersion>
<AssemblyVersion>1.17.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="partitionKey" Type="System.Object" />
</Parameters>
<Docs>
<param name="partitionKey">The partition key used to determine the target collections for reading. Must be a string.</param>
<summary>
Given a partition key, returns a list of collection links to read from using its hash in the Azure DocumentDB database service.
</summary>
<returns>The list of target collection links.</returns>
<remarks>
If partitionKey is null, then all collections are returned. The HashPartitionResolver supports only strings as partitionKeys.
For other types, use ToString() or JsonConvert.SerializeObject() to convert to string.
</remarks>
<exception cref="T:System.InvalidOperationException">Thrown if the partition key is not a string.</exception>
</Docs>
</Member>
</Members>
</Type>