From d6785732b7de70e10ea4b4fb941bbf57fb694bd4 Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Wed, 12 Nov 2025 22:38:19 +0200 Subject: [PATCH 1/7] RDoc-3570 Fix article "document identifier generation" (v7.1) --- ..._document-identifier-generation-csharp.mdx | 531 ++++++++++++++++++ .../kb/document-identifier-generation.mdx | 282 +--------- 2 files changed, 540 insertions(+), 273 deletions(-) create mode 100644 docs/server/kb/_document-identifier-generation-csharp.mdx diff --git a/docs/server/kb/_document-identifier-generation-csharp.mdx b/docs/server/kb/_document-identifier-generation-csharp.mdx new file mode 100644 index 0000000000..ad5efcd410 --- /dev/null +++ b/docs/server/kb/_document-identifier-generation-csharp.mdx @@ -0,0 +1,531 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* A document identifier (document ID) is a unique string associated with a document. + It is globally unique in the scope of the database - no two documents in the same database can have the same ID. + +* This article focuses on the different **Document ID Types** available in RavenDB and when to use each one. + Additional explanation is available in [Working with document identifiers](../../client-api/document-identifiers/working-with-document-identifiers.mdx). + To create a document from the Studio, see [Create new document](../../studio/database/documents/create-new-document.mdx#create-new-document). + +* In this article: + * [Overview](../../server/kb/document-identifier-generation.mdx#overview) + * [ID types](../../server/kb/document-identifier-generation.mdx#id-types) + * [ID structure](../../server/kb/document-identifier-generation.mdx#id-structure) + * [ID limitations](../../server/kb/document-identifier-generation.mdx#id-limitations) + * [Document IDs:](../../server/kb/document-identifier-generation.mdx#document-ids) + * [Semantic ID](../../server/kb/document-identifier-generation.mdx#semantic-id) + * [GUID](../../server/kb/document-identifier-generation.mdx#guid) + * [Server-side ID](../../server/kb/document-identifier-generation.mdx#server-side-id) + * [Identity ID](../../server/kb/document-identifier-generation.mdx#identity-id) + * [HiLo algorithm ID](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + * [Artificial document ID](../../server/kb/document-identifier-generation.mdx#artificial-document-id) + * [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character) + + + + + + +### ID types + +RavenDB supports several document ID types, where the ID string can be generated in different ways: + +* **Defined by the user**: + You explicitly specify the document ID. + * [Semantic ID](../../server/kb/document-identifier-generation.mdx#semantic-id) + +* **Generated by the server**: + The server generates the document ID based on the ID string format you provide when creating the document. + * [GUID](../../server/kb/document-identifier-generation.mdx#guid) + * [Server-side ID](../../server/kb/document-identifier-generation.mdx#server-side-id) + * [Identity ID](../../server/kb/document-identifier-generation.mdx#identity-id) + +* **Generated by the client (from a range provided by the server)**: + The server assigns a range of IDs to the client upon request. + The client then uses that range to generate document IDs locally within the session. + * [HiLo algorithm ID](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + +* **Generated from a Map-Reduce index output**: + The ID is generated by the server when saving map-reduce results as artificial documents. + * [Artificial document ID](../../server/kb/document-identifier-generation.mdx#artificial-document-id) + + + + +### ID Structure + +Document IDs typically consist of three parts: +the collection prefix, a slash (_'/'_) as the default separator, and a unique suffix. +For example: `users/123-A` (HiLo ID), or `users/000000000001-A` (Server-side ID). + +This structure is common but not mandatory: + * RavenDB does not require the ID to include a collection prefix. + * The default slash separator (`/`) can be **customized** for [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + and [Identity IDs](../../server/kb/document-identifier-generation.mdx#identity-id). => see how below.... + + + + +### ID Limitations + +The following limitations apply to document IDs: + +* Maximum length: `512` bytes (in UTF-8) +* Document IDs cannot end with the following reserved characters: + * `/` - reserved for [Server-side ID generation](../../server/kb/document-identifier-generation.mdx#server-side-id) + * `|` - reserved for [Identity ID generation](../../server/kb/document-identifier-generation.mdx#identity-id) + + + + +## Document IDs: + + + +* **Generated by**: + The user + +* **Description**: + * The **semantic ID** is assigned by _you_ when creating the document (using the Client API or from the Studio), + and not generated by the server. It’s therefore your responsibility to ensure that each ID is unique. + * Creating a new document with an existing semantic ID will _overwrite_ the existing document. + +* **When to use**: + Use a semantic ID when you want the document’s identifier to convey meaning, + to reflect what the document represents. + +* **Example**: + * Documents that use an _email_ address as a unique identifier in the _Users_ collection: + * `users/ayende@ayende.com` + * `users/john@john.doe` + This makes the ID both globally unique and instantly meaningful. + It is clear which user the document represents. + * IDs that describe the document’s contents: + * `accounts/591-192/txs/2025-11-12` + Implying that the document holds all the transactions for account 591-192 on November 12th, 2025. + * `support-tickets/INV-88411` + A support ticket related to invoice 88411. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Specify the semantic ID in the entity's Id property + var user = new User { Name = "John", Id = "users/john@john.doe" }; + session.Store(user); + + session.SaveChanges(); + // The document will be saved with the ID you specified: "users/john@john.doe" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify the semantic ID when calling Store() + session.Store(user, "users/john@john.doe"); + + session.SaveChanges(); + // The document will be saved with the ID you specified: "users/john@john.doe" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * If you don’t specify a document ID when creating the document, + the server will generate a **globally unique identifier** (GUID) for the new document. + * Although this is a simple way to generate a document ID, GUIDs are not human-friendly + and make debugging or troubleshooting more difficult. This approach is generally less recommended. + +* **When to use**: + Use this only when you don’t care about the document ID and don’t need to trace it in logs, tools, or support. + +* **Example**: + A GUID as a document ID: + `50bbe329-6258-4634-be24-2f013d7174cd` + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to string.Empty + var user = new User { Name = "John", Id = string.Empty }; + session.Store(user); + + session.SaveChanges(); + // The server will generate a GUID-based ID, e.g. "50bbe329-6258-4634-be24-2f013d7174cd" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify string.Empty when calling Store() + session.Store(user, string.Empty); + + session.SaveChanges(); + // The server will generate a GUID-based ID, e.g. "50bbe329-6258-4634-be24-2f013d7174cd" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * When you create a document and provide an ID string that ends with a _slash_ (`/`), + the server will generate the full document ID for you. + * The server handling the request increments its [last document etag](../../glossary/etag.mdx) and appends it, + along with the **server's node tag**, to the string you provided. + * Since the _etag_ reflects any document change (add, update, delete), + the generated server-side IDs are always increasing but not guaranteed to be sequential. + +* **When to use**: + * Use the server-side ID when you don't care about the exact ID given to a newly created document. + * Recommended when creating many documents (e.g., during bulk insert), + as this method has the least overhead and requires minimal work from the server. + +* **Example**: + * On a server running on node 'A': + * Creating the first document with `users/` => results in document ID: `users/0000000000000000001-A` + * Creating a second document with `users/` => results in document ID: `users/0000000000000000002-A` + * On a server running on node 'B': + * Creating a third document with `users/` => may result in: `users/0000000000000000034-B` + * Note: node tag 'B' was appended to the ID generated because the request was handled by node 'B'. + Since each server has its own local _etag_, the numeric part of the ID is _not_ necessarily sequential (or unique) across the nodes + in the database group, as can happen when documents are created in parallel on multiple nodes during network partitions or failover. + +* **Note**: + If you _manually_ generate a document ID with a pattern that matches the server-side generated IDs, + RavenDB will _not_ check for that and will overwrite the existing document. + The leading zeros in server-side generated IDs help reduce the risk of such accidental collisions. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to "users/" + var user = new User { Name = "John", Id = "users/" }; + session.Store(user); + + session.SaveChanges(); + // The server will generate a server-side ID, e.g. "users/0000000000000000001-A" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify "users/" when calling Store() + session.Store(user, "users/"); + + session.SaveChanges(); + // The server will generate a server-side ID, e.g. "users/0000000000000000001-A" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * When you create a document and provide an ID string that ends with a _pipe_ symbol (`|`), + the server will generate an **identity** ID. + * The server replaces the _pipe_ with a separator character (_slash_ (`/`) by default) and appends + an always-incrementing number. + * Unlike the server-side ID, identity numbers are guaranteed to be **globally unique** across all nodes + in the database group. + +* **When to use**: + Use an identity ID only if you truly need document IDs that are incrementing. + For example, when generating invoice numbers or to meet legal or business requirements. + + Using an identity guarantees that IDs will increment, but doesn't guarantee that the sequence will be gapless. + Gaps may occur if documents are deleted or if a transaction fails after incrementing the counter. + For example: `companies/1`, `companies/2`, `companies/4`... + + +* **Example**: + * On a server running on node 'A': + * Creating the first document with `users|` => results in document ID: `users/1` + * Creating a second document with `users|` => results in document ID: `users/2` + * On a server running on node 'B': + * Creating a third document with `users|` => results in document ID: `users/3` + +* **Note**: + * Identity ID generation comes with a real cost. + In a cluster, where the database is replicated across multiple nodes, + the nodes must coordinate to ensure the same identity ID isn’t generated on two nodes. + This coordination requires network round-trips. + + * Moreover, if the server cannot reach the majority of nodes in the database group, + saving the document will fail because the next identity value cannot be generated. + + * All other ID generation methods continue to work even when the server is disconnected from the cluster. + So unless you specifically require incremental IDs, it’s better to use a different ID generation strategy. + +* **Customizing the separator character**: + The separator character used in the identity IDs can be customized. + Learn more in [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + +* **Customizing the identity number**: + The numeric part of an identity ID is an always-incrementing value managed by the server. + You can modify the latest identity number used for a given prefix (typically a collection name) in the following ways. + The server will base the next generated identity ID on the updated value you provide. + * **From the Client API**: + Use the [NextIdentityForOperation](../../client-api/operations/maintenance/identities/increment-next-identity.mdx) to increment the latest identity number. + Use the [SeedIdentityForOperation](../../client-api/operations/maintenance/identities/seed-identity.mdx) to explicitly set its starting value. + * **From the Studio**: + Go to the [Identities view](../../studio/database/documents/identities-view.mdx) to view or edit the latest identity number for any prefix. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to "users|" + var user = new User { Name = "John", Id = "users|" }; + session.Store(user); + + session.SaveChanges(); + // The server will generate an identity ID, e.g. "users/1" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify "users|" when calling Store() + session.Store(user, "users|"); + + session.SaveChanges(); + // The server will generate an identity ID, e.g. "users/1" +} +``` + + + + + + +* **Generated by**: + The client (from a range provided by the server) + +* **Description**: + * The HiLo algorithm allows generating document IDs on the **client side**. + * The client requests a range of IDs from the server, + and the server ensures that this range is reserved exclusively for that client. + * Different clients receive different, non-overlapping ranges. + * The client can then safely generate IDs locally within the given range, + without further coordination with the server. + * For a more detailed explanation, see [HiLo Algorithm](../../client-api/document-identifiers/hilo-algorithm.mdx). + +* **When to use**: + Use HiLo when you want to create a document and immediately use its ID within the same transaction, + without needing an additional server call to fetch the ID. + +* **Example**: + `people/128-A`, `people/129-B` + +* **Customizing the separator character**: + The separator character used in the HiLo document IDs can be customized. + Learn more in [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Do not set the Id property of the entity + var user = new User { Name = "John" }; + + // Pass only the entity to Store(), without specifying an ID + session.Store(user); + + // The ID is already available here because the client holds a reserved range from the server + var documentId = user.Id; + + session.SaveChanges(); + // The document will be saved with the ID assigned by the session, e.g. "users/1-A" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * The output of a Map-Reduce index can be saved as artificial documents in a new collection. + * Their IDs are generated automatically by the server. + Each ID consists of a prefix, which is the name of the output collection you specify, + followed by a hash of the _reduce_ key that you cannot control. + * For a more detailed explanation, see [Artificial Documents](../../indexes/map-reduce-indexes.mdx#reduce-results-as-artificial-documents). + +* **When to use**: + Use artificial documents when you need to further process Map-Reduce index results, for example: + * Creating a recursive Map-Reduce index over the resulting artificial documents. + * Running ETL tasks or Subscriptions on the resulting artificial documents collection for further processing. + +* **Example**: + `MonthlyProductSales/1377/0576973199715021` + + + + + +The separator character used in the [Identity](../../server/kb/document-identifier-generation.mdx#identity-id) +and [HiLo](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) document IDs can be customized. +By default, the separator is a _slash_ (`/`), but this can be changed to any other character, except _pipe_ (`|`). + +There are several ways to customize the separator. +It can be configured globally for all databases (server-wide), or per database, overriding the global setting. + +--- + +### From the Studio: + +* Configure the separator character globally in: [Client configuration (server-wide)](../../studio/server/client-configuration.mdx). +* Override the global setting for a specific database in: [Client configuration (per database)](../../studio/database/settings/client-configuration-per-database.mdx). +* This will apply to both **Identity** & **HiLo** IDs. + +--- + +### From the Client API - using operations: + +* Set the separator globally using the [PutServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx). +* Override the global setting for a specific database using the [PutClientConfigurationOperation](../../client-api/operations/maintenance/configuration/put-client-configuration.mdx). +* This will apply to both **Identity** & **HiLo** IDs. + + +```csharp +// For example, set the separator character for a specific database + +var store = new DocumentStore +{ + Urls = new[] { "http://localhost:8080" }, + Database = "SampleDB" +}.Initialize(); + +// Customize the separator character to '#' instead of the default '/' +// using the 'PutClientConfigurationOperation' operation + store.Maintenance.Send(new PutClientConfigurationOperation( + new ClientConfiguration { IdentityPartsSeparator = '#' }));; + +using (var session = store.OpenSession()) +{ + // Create document - HiLo ID + // ========================= + var user1 = new User() { Name = "John" }; + session.Store(user1); + + // The session assigns the id immediately + var id = user1.Id; // "users#1-A" + + session.SaveChanges(); + // The document is saved with ID: "users#1-A" + + // Create document - Identity ID + // ============================= + var user2 = new User() { Name = "Jane" }; + session.Store(user2, "users|"); + + session.SaveChanges(); + // The document is saved with ID: "users#1" +} +``` + + +--- + +## From the Client API - using conventions: + +* For HiLo IDs, you can also set the separator character using the [IdentityPartsSeparator convention](../../client-api/configuration/conventions.mdx#identitypartsseparator) + on the _DocumentStore_ during initialization. +* Note: Any separator configured later via an operation or from the Studio will override this convention. +* This **applies only to HiLo IDs** and has no effect on Identity IDs. + + +```csharp +// Set the separator character for HiLo ID via conventions +var store = new DocumentStore +{ + Urls = new[] { "http://localhost:8080" }, + Database = "SampleDB", + Conventions = new DocumentConventions + { + IdentityPartsSeparator = '$', + // ... set any other conventions as needed + } +}.Initialize(); + +using (var session = store.OpenSession()) +{ + // Create document - HiLo ID + // ========================= + var user1 = new User() { Name = "John" }; + session.Store(user1); + + // The session assigns the id immediately + var id = user1.Id; // "users$1-A" + + session.SaveChanges(); + // The document is saved with ID: "users$1-A" + + // Create document - Identity ID + // ============================= + var user2 = new User() { Name = "Jane" }; + session.Store(user2, "users|"); + + session.SaveChanges(); + // The document is saved with ID: "users/1" (uses default separator '/') +} +``` + + \ No newline at end of file diff --git a/docs/server/kb/document-identifier-generation.mdx b/docs/server/kb/document-identifier-generation.mdx index 37de63e9c2..c3536cff00 100644 --- a/docs/server/kb/document-identifier-generation.mdx +++ b/docs/server/kb/document-identifier-generation.mdx @@ -1,284 +1,20 @@ ---- -title: "Knowledge Base: Document Identifier Generation" +--- +title: "Document Identifier Generation" hide_table_of_contents: true -sidebar_label: Document Identifier Generation +sidebar_label: "Document Identifier Generation" sidebar_position: 0 --- -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Knowledge Base: Document Identifier Generation - - -* A **Document Identifier**, `ID` in short, is a unique identification string associated with the document. - IDs are globally unique in the scope of the database: no two documents in the same - database will have the same ID. - -* IDs can be generated using different [strategies](../../server/kb/document-identifier-generation.mdx#id-generation-strategies): - by **a client**, by **the server**, by **client-server collaboratoin**, - or by a **map-reduce index output**. - -* In this page: - * [Document IDs](../../server/kb/document-identifier-generation.mdx#document-ids) - * [ID Generation Strategies](../../server/kb/document-identifier-generation.mdx#id-generation-strategies) - * [ID Structure](../../server/kb/document-identifier-generation.mdx#id-structure) - * [ID Limitations](../../server/kb/document-identifier-generation.mdx#id-limitations) - * [ID Generation by Client](../../server/kb/document-identifier-generation.mdx#id-generation-by-client) - * [Strategy: `Semantic ID`](../../server/kb/document-identifier-generation.mdx#strategy-) - * [ID Generation by Server](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) - * [Strategy: `GUID`](../../server/kb/document-identifier-generation.mdx#strategy--1) - * [Strategy: `Server-Side ID`](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Strategy: `Identity`](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [ID Generation by Client-Server Collaboration](../../server/kb/document-identifier-generation.mdx#id-generation-by-client-server-collaboration) - * [Strategy: `HiLo Algorithm`](../../server/kb/document-identifier-generation.mdx#strategy--4) - * [ID Generation by Map-Reduce Index Output](../../server/kb/document-identifier-generation.mdx#id-generation-by-map-reduce-index-output) - * [Strategy: `Artificial Document ID`](../../server/kb/document-identifier-generation.mdx#strategy--5) - - -## Document IDs - -### ID Generation Strategies - -Document identifiers can be generated using the following strategies: -Click a strategy to read more about its implementation. - -* By [a Client](../../server/kb/document-identifier-generation.mdx#id-generation-by-client) -* By [the Server](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) -* By [Client-Server Collaboratoin](../../server/kb/document-identifier-generation.mdx#id-generation-by-client-server-collaboration) -* By [Map-Reduce Index Output](../../server/kb/document-identifier-generation.mdx#id-generation-by-map-reduce-index-output) -### ID Structure - -The document ID is typiclly composed of the collection name as prefix, a slash (`/`), and the unique ID portion -(including a node tag, e.g. `A`, indicating which server node the document resides on). -E.g.: `users/1-A` - -Note that this behavior is **not** mandatory: - -* RavenDB does not require the collection prefix to be included in the ID string. -* The [Identifier Parts Separator](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) can be replaced. -### ID Limitations - -The following limitations apply to document IDs: - -* Identifiers length limit: **512 bytes** (in UTF8) -* Identifiers cannot end with the following reserved characters: - `/` (reserved for Server-Side ID) - `|` (reserved for Identity generation) - - - -## ID Generation by Client -### Strategy: `Semantic ID` - -* **Generated by**: - The user - -* **Description**: - * The **semantic ID** is generated by _the user_ (using the Client API or from the Studio) and not by RavenDB server. - As such, it is the user's responsibility to generate unique IDs. - * Creating a new document with an existing semantic ID will _overwrite_ the existing document. - -* **When to use**: - Use a semantic ID when you want the document to have an identifier that has some meaningful value. - -* **Example**: - * Documents with a unique semantic ID containing a user's _email_ can be generated under the 'Users' collection: - * users/ayende@ayende.com - * users/john@john.doe - * For clarity, the document content can be indicated within the Semantic ID string: - * accounts/591-192/txs/2017-05-17 - Implying that the document holds all the transactions from May 17th, 2017 for account 591-192 - - -## ID Generation by Server - - -By default, the components of document IDs created by the server are separated by the `/` character. -This default separator can be replaced with any other character except `|` -in the [Document Store Conventions](../../client-api/configuration/conventions.mdx#changing-the-identity-separator). - -Examples: - - - - -{`// Change the ID separator from the default \`/\` to \`-\` -store.Maintenance.Send( - new PutClientConfigurationOperation( - new ClientConfiguration { IdentityPartsSeparator = '-' })); - -using (var session = store.OpenSession()) -{ - // The \`|\` causes the cluster to generate an identity - // The ID is unique over the whole cluster - // The first generated ID will be \`Prefix-1\` - session.Store(new User - { - Name = "John", - Id = "Prefix|" - }); - - session.SaveChanges(); -} -`} - - - - -{`// Change the ID separator from the default \`/\` to \`-\` -store.Maintenance.Send( - new PutClientConfigurationOperation( - new ClientConfiguration { IdentityPartsSeparator = '-' })); - -using (var session = store.OpenSession()) -{ - // Since an ID wasn't explicitly provided, the server generates one. - // The first generated ID on node A will be \`users-1-A\` - session.Store(new User - { - Name = "John", - }); - - session.SaveChanges(); -} -`} - - - - - -### Strategy: `Guid` - -* **Generated by**: - The server - -* **Description**: - * When a document ID is _not_ specified, RavenDB server will generate a **globally unique identifier** (GUID) for the stored new document. - * Although this is the simplest way to generate a document ID, Guids are _not_ human-friendly when it comes to debugging or troubleshooting - and are less recommended. - -* **When to use**: - Only When you don't care about the exact ID generated and about the ease of troubleshooting your app... -### Strategy: `Server-Side ID` - -* **Generated by**: - The server - -* **Description**: - * Upon document creation, providing a document ID string that ends with a _slash_ ( / ) will cause the server to generate a **server-side ID**. - * The RavenDB server that is handling the request will increment the value of its [Last Document Etag](../../glossary/etag.mdx). - This _Etag_ and the _Server Node Tag_ are appended by the server to the end of the ID string provided. - * Since the etag on which the ID is based changes upon any adding, deleting, or updating a document, - the only guarantee about the Server-Side ID is that it is always increasing, but not always sequential. - -* **When to use**: - * Use the server-side ID when you don't care about the exact ID that is given to a newly created document. - * Recommended when a large number of documents are needed to be created, such as in bulk insert scenarios, - as this method requires the least amount of work from RavenDB. - -* **Example**: - * From a server running on node 'A': - * Creating the first document with 'users/' => will result with document ID: _'users/0000000000000000001-A'_ - * Creating a second document with 'users/' => will result with document ID: _'users/0000000000000000002-A'_ - * From a server running on node 'B': - * Creating a third document with 'users/' => can result for example with document ID: _'users/0000000000000000034-B'_ - * Note: node tag 'B' was appended to the ID generated, as the server handling the request is on node 'B'. - But, since each server has its own local Etag, the numeric part in the ID will _not_ necessarily be sequential (or unique) across the nodes - within the database group in the cluster, as can happen when creating documents at partition time. - -* **Note**: - If you _manually_ generate a document ID with a pattern that matches the server-side generated IDs, - RavenDB will _not_ check for that and will overwrite the existing document. - The leading zeros help avoid such conflicts with any existing document by accident. -### Strategy: `Identity` - -* **Generated by**: - The server - -* **Description**: - * Upon document creation, providing a document ID string that ends with a _pipe symbol_ (`|`) will cause the server to generate an **identity**. - * RavenDb will create a simple, always-incrementing value and append it to the ID string provided (replacing the pipe with a slash). - * As opposed to the Server-Side ID, This value _will be unique_ across all the nodes within the Database Group in the cluster. - -* **When to use**: - Use an identity only if you really need documents with incremental IDs, - i.e. when generating invoices, or upon legal obligation. - - Using an identity guarantees that IDs will be incremental, but does **not** guarantee - that there wouldn't be gaps in the sequence. - The IDs sequence can therefore be, for example, `companies/1`, `companies/2`, `companies/4`.. - This is because - - - * Documents could have been deleted. - * A failed transaction still increments the identity value, thus causing a gap in the sequence. - - - -* **Example**: - * From a server running on node 'A': - * Creating the first document with 'users|' => will result with document ID: _'users/1'_ - * Creating a second document with 'users|' => will result with document ID: _'users/2'_ - * From a server running on node 'B': - * Creating a third document with 'users|' => will result with document ID: _'users/3'_ - -* **Note**: - * Identity has a real cost associated with it. - Generating identities in a cluster where the database is replicated across more than one node requires a lot of work. - * Network round trips are required as the nodes must coordinate with one another so that the same identity is _not_ generated on 2 different nodes in the cluster. - * Moreover, upon a failure scenario, if the node cannot communicate with the other cluster members, or the majority of nodes cannot be communicated with, - saving the document will fail as the requested identity cannot be generated. - * All the other ID generation methods can work without any issue when the server is disconnected from the cluster, - so unless you truly need incremental IDs, use one of the other options. - - - -## ID Generation by Client-Server Collaboration -### Strategy: `HiLo Algorithm` - -* **Generated by**: - Both the server and the client - -* **Description**: - * The Hilo algorithm enables generating document IDs on the client. - * The client reserves a range of identifiers from the server and the server ensures that this range will be provided only to this client. - * Different clients will receive different ranges. - * Each client can then safely generate identifiers within the range it was given, no further coordination with the server is required. - * For a more detailed explanation see [HiLo Algorithm](../../client-api/document-identifiers/hilo-algorithm.mdx) - -* **When to use**: - When you want to write code on the client that will create a new document and use its ID immediately in the same transaction, - without making another call to the server to get the ID and use it in a separate transaction. - -* **Example**: - people/128-A, people/129-B - - - -## ID Generation by Map-Reduce Index Output -### Strategy: `Artificial Document ID` - -* **Generated by**: - The server - -* **Description**: - * The output from a Map-Reduce index can be saved as Artificial Documents in a new collection. - * You have no control over these artificial documetns IDs, they are generated by RavenDB based on the hash of the reduce key. - * For a more detailed explanation see [Artificial Documents](../../indexes/map-reduce-indexes.mdx#reduce-results-as-artificial-documents) - abd the creation of their [IDs](../../indexes/map-reduce-indexes.mdx#ids). - -* **When to use**: - When you need to further process the Map-Reduce index results by: - * Having a recursive Map-Reduce index operation, setting up indexes on top of the Artificial Documents. - * Setting up a RavenDB ETL Task on the Artificial Documents collection to a dedicated database on - a separate cluster for further processing, as well as other ongoing tasks such as: SQL ETL and Subscriptions. +import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; -* **Example**: - MonthlyProductSales/13770576973199715021 +export const supportedLanguages = ["csharp"]; + + + + From f317efc767fb28fe5349f9a9456a58eba11abec9 Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Fri, 14 Nov 2025 20:09:23 +0200 Subject: [PATCH 2/7] RDoc-3570 Fix article "document identifier generation" (v7.0, v6.2) --- ..._document-identifier-generation-csharp.mdx | 531 ++++++++++++++++++ .../kb/document-identifier-generation.mdx | 282 +--------- ..._document-identifier-generation-csharp.mdx | 531 ++++++++++++++++++ .../kb/document-identifier-generation.mdx | 282 +--------- 4 files changed, 1080 insertions(+), 546 deletions(-) create mode 100644 versioned_docs/version-6.2/server/kb/_document-identifier-generation-csharp.mdx create mode 100644 versioned_docs/version-7.0/server/kb/_document-identifier-generation-csharp.mdx diff --git a/versioned_docs/version-6.2/server/kb/_document-identifier-generation-csharp.mdx b/versioned_docs/version-6.2/server/kb/_document-identifier-generation-csharp.mdx new file mode 100644 index 0000000000..ad5efcd410 --- /dev/null +++ b/versioned_docs/version-6.2/server/kb/_document-identifier-generation-csharp.mdx @@ -0,0 +1,531 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* A document identifier (document ID) is a unique string associated with a document. + It is globally unique in the scope of the database - no two documents in the same database can have the same ID. + +* This article focuses on the different **Document ID Types** available in RavenDB and when to use each one. + Additional explanation is available in [Working with document identifiers](../../client-api/document-identifiers/working-with-document-identifiers.mdx). + To create a document from the Studio, see [Create new document](../../studio/database/documents/create-new-document.mdx#create-new-document). + +* In this article: + * [Overview](../../server/kb/document-identifier-generation.mdx#overview) + * [ID types](../../server/kb/document-identifier-generation.mdx#id-types) + * [ID structure](../../server/kb/document-identifier-generation.mdx#id-structure) + * [ID limitations](../../server/kb/document-identifier-generation.mdx#id-limitations) + * [Document IDs:](../../server/kb/document-identifier-generation.mdx#document-ids) + * [Semantic ID](../../server/kb/document-identifier-generation.mdx#semantic-id) + * [GUID](../../server/kb/document-identifier-generation.mdx#guid) + * [Server-side ID](../../server/kb/document-identifier-generation.mdx#server-side-id) + * [Identity ID](../../server/kb/document-identifier-generation.mdx#identity-id) + * [HiLo algorithm ID](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + * [Artificial document ID](../../server/kb/document-identifier-generation.mdx#artificial-document-id) + * [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character) + + + + + + +### ID types + +RavenDB supports several document ID types, where the ID string can be generated in different ways: + +* **Defined by the user**: + You explicitly specify the document ID. + * [Semantic ID](../../server/kb/document-identifier-generation.mdx#semantic-id) + +* **Generated by the server**: + The server generates the document ID based on the ID string format you provide when creating the document. + * [GUID](../../server/kb/document-identifier-generation.mdx#guid) + * [Server-side ID](../../server/kb/document-identifier-generation.mdx#server-side-id) + * [Identity ID](../../server/kb/document-identifier-generation.mdx#identity-id) + +* **Generated by the client (from a range provided by the server)**: + The server assigns a range of IDs to the client upon request. + The client then uses that range to generate document IDs locally within the session. + * [HiLo algorithm ID](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + +* **Generated from a Map-Reduce index output**: + The ID is generated by the server when saving map-reduce results as artificial documents. + * [Artificial document ID](../../server/kb/document-identifier-generation.mdx#artificial-document-id) + + + + +### ID Structure + +Document IDs typically consist of three parts: +the collection prefix, a slash (_'/'_) as the default separator, and a unique suffix. +For example: `users/123-A` (HiLo ID), or `users/000000000001-A` (Server-side ID). + +This structure is common but not mandatory: + * RavenDB does not require the ID to include a collection prefix. + * The default slash separator (`/`) can be **customized** for [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + and [Identity IDs](../../server/kb/document-identifier-generation.mdx#identity-id). => see how below.... + + + + +### ID Limitations + +The following limitations apply to document IDs: + +* Maximum length: `512` bytes (in UTF-8) +* Document IDs cannot end with the following reserved characters: + * `/` - reserved for [Server-side ID generation](../../server/kb/document-identifier-generation.mdx#server-side-id) + * `|` - reserved for [Identity ID generation](../../server/kb/document-identifier-generation.mdx#identity-id) + + + + +## Document IDs: + + + +* **Generated by**: + The user + +* **Description**: + * The **semantic ID** is assigned by _you_ when creating the document (using the Client API or from the Studio), + and not generated by the server. It’s therefore your responsibility to ensure that each ID is unique. + * Creating a new document with an existing semantic ID will _overwrite_ the existing document. + +* **When to use**: + Use a semantic ID when you want the document’s identifier to convey meaning, + to reflect what the document represents. + +* **Example**: + * Documents that use an _email_ address as a unique identifier in the _Users_ collection: + * `users/ayende@ayende.com` + * `users/john@john.doe` + This makes the ID both globally unique and instantly meaningful. + It is clear which user the document represents. + * IDs that describe the document’s contents: + * `accounts/591-192/txs/2025-11-12` + Implying that the document holds all the transactions for account 591-192 on November 12th, 2025. + * `support-tickets/INV-88411` + A support ticket related to invoice 88411. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Specify the semantic ID in the entity's Id property + var user = new User { Name = "John", Id = "users/john@john.doe" }; + session.Store(user); + + session.SaveChanges(); + // The document will be saved with the ID you specified: "users/john@john.doe" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify the semantic ID when calling Store() + session.Store(user, "users/john@john.doe"); + + session.SaveChanges(); + // The document will be saved with the ID you specified: "users/john@john.doe" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * If you don’t specify a document ID when creating the document, + the server will generate a **globally unique identifier** (GUID) for the new document. + * Although this is a simple way to generate a document ID, GUIDs are not human-friendly + and make debugging or troubleshooting more difficult. This approach is generally less recommended. + +* **When to use**: + Use this only when you don’t care about the document ID and don’t need to trace it in logs, tools, or support. + +* **Example**: + A GUID as a document ID: + `50bbe329-6258-4634-be24-2f013d7174cd` + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to string.Empty + var user = new User { Name = "John", Id = string.Empty }; + session.Store(user); + + session.SaveChanges(); + // The server will generate a GUID-based ID, e.g. "50bbe329-6258-4634-be24-2f013d7174cd" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify string.Empty when calling Store() + session.Store(user, string.Empty); + + session.SaveChanges(); + // The server will generate a GUID-based ID, e.g. "50bbe329-6258-4634-be24-2f013d7174cd" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * When you create a document and provide an ID string that ends with a _slash_ (`/`), + the server will generate the full document ID for you. + * The server handling the request increments its [last document etag](../../glossary/etag.mdx) and appends it, + along with the **server's node tag**, to the string you provided. + * Since the _etag_ reflects any document change (add, update, delete), + the generated server-side IDs are always increasing but not guaranteed to be sequential. + +* **When to use**: + * Use the server-side ID when you don't care about the exact ID given to a newly created document. + * Recommended when creating many documents (e.g., during bulk insert), + as this method has the least overhead and requires minimal work from the server. + +* **Example**: + * On a server running on node 'A': + * Creating the first document with `users/` => results in document ID: `users/0000000000000000001-A` + * Creating a second document with `users/` => results in document ID: `users/0000000000000000002-A` + * On a server running on node 'B': + * Creating a third document with `users/` => may result in: `users/0000000000000000034-B` + * Note: node tag 'B' was appended to the ID generated because the request was handled by node 'B'. + Since each server has its own local _etag_, the numeric part of the ID is _not_ necessarily sequential (or unique) across the nodes + in the database group, as can happen when documents are created in parallel on multiple nodes during network partitions or failover. + +* **Note**: + If you _manually_ generate a document ID with a pattern that matches the server-side generated IDs, + RavenDB will _not_ check for that and will overwrite the existing document. + The leading zeros in server-side generated IDs help reduce the risk of such accidental collisions. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to "users/" + var user = new User { Name = "John", Id = "users/" }; + session.Store(user); + + session.SaveChanges(); + // The server will generate a server-side ID, e.g. "users/0000000000000000001-A" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify "users/" when calling Store() + session.Store(user, "users/"); + + session.SaveChanges(); + // The server will generate a server-side ID, e.g. "users/0000000000000000001-A" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * When you create a document and provide an ID string that ends with a _pipe_ symbol (`|`), + the server will generate an **identity** ID. + * The server replaces the _pipe_ with a separator character (_slash_ (`/`) by default) and appends + an always-incrementing number. + * Unlike the server-side ID, identity numbers are guaranteed to be **globally unique** across all nodes + in the database group. + +* **When to use**: + Use an identity ID only if you truly need document IDs that are incrementing. + For example, when generating invoice numbers or to meet legal or business requirements. + + Using an identity guarantees that IDs will increment, but doesn't guarantee that the sequence will be gapless. + Gaps may occur if documents are deleted or if a transaction fails after incrementing the counter. + For example: `companies/1`, `companies/2`, `companies/4`... + + +* **Example**: + * On a server running on node 'A': + * Creating the first document with `users|` => results in document ID: `users/1` + * Creating a second document with `users|` => results in document ID: `users/2` + * On a server running on node 'B': + * Creating a third document with `users|` => results in document ID: `users/3` + +* **Note**: + * Identity ID generation comes with a real cost. + In a cluster, where the database is replicated across multiple nodes, + the nodes must coordinate to ensure the same identity ID isn’t generated on two nodes. + This coordination requires network round-trips. + + * Moreover, if the server cannot reach the majority of nodes in the database group, + saving the document will fail because the next identity value cannot be generated. + + * All other ID generation methods continue to work even when the server is disconnected from the cluster. + So unless you specifically require incremental IDs, it’s better to use a different ID generation strategy. + +* **Customizing the separator character**: + The separator character used in the identity IDs can be customized. + Learn more in [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + +* **Customizing the identity number**: + The numeric part of an identity ID is an always-incrementing value managed by the server. + You can modify the latest identity number used for a given prefix (typically a collection name) in the following ways. + The server will base the next generated identity ID on the updated value you provide. + * **From the Client API**: + Use the [NextIdentityForOperation](../../client-api/operations/maintenance/identities/increment-next-identity.mdx) to increment the latest identity number. + Use the [SeedIdentityForOperation](../../client-api/operations/maintenance/identities/seed-identity.mdx) to explicitly set its starting value. + * **From the Studio**: + Go to the [Identities view](../../studio/database/documents/identities-view.mdx) to view or edit the latest identity number for any prefix. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to "users|" + var user = new User { Name = "John", Id = "users|" }; + session.Store(user); + + session.SaveChanges(); + // The server will generate an identity ID, e.g. "users/1" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify "users|" when calling Store() + session.Store(user, "users|"); + + session.SaveChanges(); + // The server will generate an identity ID, e.g. "users/1" +} +``` + + + + + + +* **Generated by**: + The client (from a range provided by the server) + +* **Description**: + * The HiLo algorithm allows generating document IDs on the **client side**. + * The client requests a range of IDs from the server, + and the server ensures that this range is reserved exclusively for that client. + * Different clients receive different, non-overlapping ranges. + * The client can then safely generate IDs locally within the given range, + without further coordination with the server. + * For a more detailed explanation, see [HiLo Algorithm](../../client-api/document-identifiers/hilo-algorithm.mdx). + +* **When to use**: + Use HiLo when you want to create a document and immediately use its ID within the same transaction, + without needing an additional server call to fetch the ID. + +* **Example**: + `people/128-A`, `people/129-B` + +* **Customizing the separator character**: + The separator character used in the HiLo document IDs can be customized. + Learn more in [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Do not set the Id property of the entity + var user = new User { Name = "John" }; + + // Pass only the entity to Store(), without specifying an ID + session.Store(user); + + // The ID is already available here because the client holds a reserved range from the server + var documentId = user.Id; + + session.SaveChanges(); + // The document will be saved with the ID assigned by the session, e.g. "users/1-A" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * The output of a Map-Reduce index can be saved as artificial documents in a new collection. + * Their IDs are generated automatically by the server. + Each ID consists of a prefix, which is the name of the output collection you specify, + followed by a hash of the _reduce_ key that you cannot control. + * For a more detailed explanation, see [Artificial Documents](../../indexes/map-reduce-indexes.mdx#reduce-results-as-artificial-documents). + +* **When to use**: + Use artificial documents when you need to further process Map-Reduce index results, for example: + * Creating a recursive Map-Reduce index over the resulting artificial documents. + * Running ETL tasks or Subscriptions on the resulting artificial documents collection for further processing. + +* **Example**: + `MonthlyProductSales/1377/0576973199715021` + + + + + +The separator character used in the [Identity](../../server/kb/document-identifier-generation.mdx#identity-id) +and [HiLo](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) document IDs can be customized. +By default, the separator is a _slash_ (`/`), but this can be changed to any other character, except _pipe_ (`|`). + +There are several ways to customize the separator. +It can be configured globally for all databases (server-wide), or per database, overriding the global setting. + +--- + +### From the Studio: + +* Configure the separator character globally in: [Client configuration (server-wide)](../../studio/server/client-configuration.mdx). +* Override the global setting for a specific database in: [Client configuration (per database)](../../studio/database/settings/client-configuration-per-database.mdx). +* This will apply to both **Identity** & **HiLo** IDs. + +--- + +### From the Client API - using operations: + +* Set the separator globally using the [PutServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx). +* Override the global setting for a specific database using the [PutClientConfigurationOperation](../../client-api/operations/maintenance/configuration/put-client-configuration.mdx). +* This will apply to both **Identity** & **HiLo** IDs. + + +```csharp +// For example, set the separator character for a specific database + +var store = new DocumentStore +{ + Urls = new[] { "http://localhost:8080" }, + Database = "SampleDB" +}.Initialize(); + +// Customize the separator character to '#' instead of the default '/' +// using the 'PutClientConfigurationOperation' operation + store.Maintenance.Send(new PutClientConfigurationOperation( + new ClientConfiguration { IdentityPartsSeparator = '#' }));; + +using (var session = store.OpenSession()) +{ + // Create document - HiLo ID + // ========================= + var user1 = new User() { Name = "John" }; + session.Store(user1); + + // The session assigns the id immediately + var id = user1.Id; // "users#1-A" + + session.SaveChanges(); + // The document is saved with ID: "users#1-A" + + // Create document - Identity ID + // ============================= + var user2 = new User() { Name = "Jane" }; + session.Store(user2, "users|"); + + session.SaveChanges(); + // The document is saved with ID: "users#1" +} +``` + + +--- + +## From the Client API - using conventions: + +* For HiLo IDs, you can also set the separator character using the [IdentityPartsSeparator convention](../../client-api/configuration/conventions.mdx#identitypartsseparator) + on the _DocumentStore_ during initialization. +* Note: Any separator configured later via an operation or from the Studio will override this convention. +* This **applies only to HiLo IDs** and has no effect on Identity IDs. + + +```csharp +// Set the separator character for HiLo ID via conventions +var store = new DocumentStore +{ + Urls = new[] { "http://localhost:8080" }, + Database = "SampleDB", + Conventions = new DocumentConventions + { + IdentityPartsSeparator = '$', + // ... set any other conventions as needed + } +}.Initialize(); + +using (var session = store.OpenSession()) +{ + // Create document - HiLo ID + // ========================= + var user1 = new User() { Name = "John" }; + session.Store(user1); + + // The session assigns the id immediately + var id = user1.Id; // "users$1-A" + + session.SaveChanges(); + // The document is saved with ID: "users$1-A" + + // Create document - Identity ID + // ============================= + var user2 = new User() { Name = "Jane" }; + session.Store(user2, "users|"); + + session.SaveChanges(); + // The document is saved with ID: "users/1" (uses default separator '/') +} +``` + + \ No newline at end of file diff --git a/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx b/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx index 37de63e9c2..c3536cff00 100644 --- a/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx +++ b/versioned_docs/version-6.2/server/kb/document-identifier-generation.mdx @@ -1,284 +1,20 @@ ---- -title: "Knowledge Base: Document Identifier Generation" +--- +title: "Document Identifier Generation" hide_table_of_contents: true -sidebar_label: Document Identifier Generation +sidebar_label: "Document Identifier Generation" sidebar_position: 0 --- -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Knowledge Base: Document Identifier Generation - - -* A **Document Identifier**, `ID` in short, is a unique identification string associated with the document. - IDs are globally unique in the scope of the database: no two documents in the same - database will have the same ID. - -* IDs can be generated using different [strategies](../../server/kb/document-identifier-generation.mdx#id-generation-strategies): - by **a client**, by **the server**, by **client-server collaboratoin**, - or by a **map-reduce index output**. - -* In this page: - * [Document IDs](../../server/kb/document-identifier-generation.mdx#document-ids) - * [ID Generation Strategies](../../server/kb/document-identifier-generation.mdx#id-generation-strategies) - * [ID Structure](../../server/kb/document-identifier-generation.mdx#id-structure) - * [ID Limitations](../../server/kb/document-identifier-generation.mdx#id-limitations) - * [ID Generation by Client](../../server/kb/document-identifier-generation.mdx#id-generation-by-client) - * [Strategy: `Semantic ID`](../../server/kb/document-identifier-generation.mdx#strategy-) - * [ID Generation by Server](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) - * [Strategy: `GUID`](../../server/kb/document-identifier-generation.mdx#strategy--1) - * [Strategy: `Server-Side ID`](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Strategy: `Identity`](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [ID Generation by Client-Server Collaboration](../../server/kb/document-identifier-generation.mdx#id-generation-by-client-server-collaboration) - * [Strategy: `HiLo Algorithm`](../../server/kb/document-identifier-generation.mdx#strategy--4) - * [ID Generation by Map-Reduce Index Output](../../server/kb/document-identifier-generation.mdx#id-generation-by-map-reduce-index-output) - * [Strategy: `Artificial Document ID`](../../server/kb/document-identifier-generation.mdx#strategy--5) - - -## Document IDs - -### ID Generation Strategies - -Document identifiers can be generated using the following strategies: -Click a strategy to read more about its implementation. - -* By [a Client](../../server/kb/document-identifier-generation.mdx#id-generation-by-client) -* By [the Server](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) -* By [Client-Server Collaboratoin](../../server/kb/document-identifier-generation.mdx#id-generation-by-client-server-collaboration) -* By [Map-Reduce Index Output](../../server/kb/document-identifier-generation.mdx#id-generation-by-map-reduce-index-output) -### ID Structure - -The document ID is typiclly composed of the collection name as prefix, a slash (`/`), and the unique ID portion -(including a node tag, e.g. `A`, indicating which server node the document resides on). -E.g.: `users/1-A` - -Note that this behavior is **not** mandatory: - -* RavenDB does not require the collection prefix to be included in the ID string. -* The [Identifier Parts Separator](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) can be replaced. -### ID Limitations - -The following limitations apply to document IDs: - -* Identifiers length limit: **512 bytes** (in UTF8) -* Identifiers cannot end with the following reserved characters: - `/` (reserved for Server-Side ID) - `|` (reserved for Identity generation) - - - -## ID Generation by Client -### Strategy: `Semantic ID` - -* **Generated by**: - The user - -* **Description**: - * The **semantic ID** is generated by _the user_ (using the Client API or from the Studio) and not by RavenDB server. - As such, it is the user's responsibility to generate unique IDs. - * Creating a new document with an existing semantic ID will _overwrite_ the existing document. - -* **When to use**: - Use a semantic ID when you want the document to have an identifier that has some meaningful value. - -* **Example**: - * Documents with a unique semantic ID containing a user's _email_ can be generated under the 'Users' collection: - * users/ayende@ayende.com - * users/john@john.doe - * For clarity, the document content can be indicated within the Semantic ID string: - * accounts/591-192/txs/2017-05-17 - Implying that the document holds all the transactions from May 17th, 2017 for account 591-192 - - -## ID Generation by Server - - -By default, the components of document IDs created by the server are separated by the `/` character. -This default separator can be replaced with any other character except `|` -in the [Document Store Conventions](../../client-api/configuration/conventions.mdx#changing-the-identity-separator). - -Examples: - - - - -{`// Change the ID separator from the default \`/\` to \`-\` -store.Maintenance.Send( - new PutClientConfigurationOperation( - new ClientConfiguration { IdentityPartsSeparator = '-' })); - -using (var session = store.OpenSession()) -{ - // The \`|\` causes the cluster to generate an identity - // The ID is unique over the whole cluster - // The first generated ID will be \`Prefix-1\` - session.Store(new User - { - Name = "John", - Id = "Prefix|" - }); - - session.SaveChanges(); -} -`} - - - - -{`// Change the ID separator from the default \`/\` to \`-\` -store.Maintenance.Send( - new PutClientConfigurationOperation( - new ClientConfiguration { IdentityPartsSeparator = '-' })); - -using (var session = store.OpenSession()) -{ - // Since an ID wasn't explicitly provided, the server generates one. - // The first generated ID on node A will be \`users-1-A\` - session.Store(new User - { - Name = "John", - }); - - session.SaveChanges(); -} -`} - - - - - -### Strategy: `Guid` - -* **Generated by**: - The server - -* **Description**: - * When a document ID is _not_ specified, RavenDB server will generate a **globally unique identifier** (GUID) for the stored new document. - * Although this is the simplest way to generate a document ID, Guids are _not_ human-friendly when it comes to debugging or troubleshooting - and are less recommended. - -* **When to use**: - Only When you don't care about the exact ID generated and about the ease of troubleshooting your app... -### Strategy: `Server-Side ID` - -* **Generated by**: - The server - -* **Description**: - * Upon document creation, providing a document ID string that ends with a _slash_ ( / ) will cause the server to generate a **server-side ID**. - * The RavenDB server that is handling the request will increment the value of its [Last Document Etag](../../glossary/etag.mdx). - This _Etag_ and the _Server Node Tag_ are appended by the server to the end of the ID string provided. - * Since the etag on which the ID is based changes upon any adding, deleting, or updating a document, - the only guarantee about the Server-Side ID is that it is always increasing, but not always sequential. - -* **When to use**: - * Use the server-side ID when you don't care about the exact ID that is given to a newly created document. - * Recommended when a large number of documents are needed to be created, such as in bulk insert scenarios, - as this method requires the least amount of work from RavenDB. - -* **Example**: - * From a server running on node 'A': - * Creating the first document with 'users/' => will result with document ID: _'users/0000000000000000001-A'_ - * Creating a second document with 'users/' => will result with document ID: _'users/0000000000000000002-A'_ - * From a server running on node 'B': - * Creating a third document with 'users/' => can result for example with document ID: _'users/0000000000000000034-B'_ - * Note: node tag 'B' was appended to the ID generated, as the server handling the request is on node 'B'. - But, since each server has its own local Etag, the numeric part in the ID will _not_ necessarily be sequential (or unique) across the nodes - within the database group in the cluster, as can happen when creating documents at partition time. - -* **Note**: - If you _manually_ generate a document ID with a pattern that matches the server-side generated IDs, - RavenDB will _not_ check for that and will overwrite the existing document. - The leading zeros help avoid such conflicts with any existing document by accident. -### Strategy: `Identity` - -* **Generated by**: - The server - -* **Description**: - * Upon document creation, providing a document ID string that ends with a _pipe symbol_ (`|`) will cause the server to generate an **identity**. - * RavenDb will create a simple, always-incrementing value and append it to the ID string provided (replacing the pipe with a slash). - * As opposed to the Server-Side ID, This value _will be unique_ across all the nodes within the Database Group in the cluster. - -* **When to use**: - Use an identity only if you really need documents with incremental IDs, - i.e. when generating invoices, or upon legal obligation. - - Using an identity guarantees that IDs will be incremental, but does **not** guarantee - that there wouldn't be gaps in the sequence. - The IDs sequence can therefore be, for example, `companies/1`, `companies/2`, `companies/4`.. - This is because - - - * Documents could have been deleted. - * A failed transaction still increments the identity value, thus causing a gap in the sequence. - - - -* **Example**: - * From a server running on node 'A': - * Creating the first document with 'users|' => will result with document ID: _'users/1'_ - * Creating a second document with 'users|' => will result with document ID: _'users/2'_ - * From a server running on node 'B': - * Creating a third document with 'users|' => will result with document ID: _'users/3'_ - -* **Note**: - * Identity has a real cost associated with it. - Generating identities in a cluster where the database is replicated across more than one node requires a lot of work. - * Network round trips are required as the nodes must coordinate with one another so that the same identity is _not_ generated on 2 different nodes in the cluster. - * Moreover, upon a failure scenario, if the node cannot communicate with the other cluster members, or the majority of nodes cannot be communicated with, - saving the document will fail as the requested identity cannot be generated. - * All the other ID generation methods can work without any issue when the server is disconnected from the cluster, - so unless you truly need incremental IDs, use one of the other options. - - - -## ID Generation by Client-Server Collaboration -### Strategy: `HiLo Algorithm` - -* **Generated by**: - Both the server and the client - -* **Description**: - * The Hilo algorithm enables generating document IDs on the client. - * The client reserves a range of identifiers from the server and the server ensures that this range will be provided only to this client. - * Different clients will receive different ranges. - * Each client can then safely generate identifiers within the range it was given, no further coordination with the server is required. - * For a more detailed explanation see [HiLo Algorithm](../../client-api/document-identifiers/hilo-algorithm.mdx) - -* **When to use**: - When you want to write code on the client that will create a new document and use its ID immediately in the same transaction, - without making another call to the server to get the ID and use it in a separate transaction. - -* **Example**: - people/128-A, people/129-B - - - -## ID Generation by Map-Reduce Index Output -### Strategy: `Artificial Document ID` - -* **Generated by**: - The server - -* **Description**: - * The output from a Map-Reduce index can be saved as Artificial Documents in a new collection. - * You have no control over these artificial documetns IDs, they are generated by RavenDB based on the hash of the reduce key. - * For a more detailed explanation see [Artificial Documents](../../indexes/map-reduce-indexes.mdx#reduce-results-as-artificial-documents) - abd the creation of their [IDs](../../indexes/map-reduce-indexes.mdx#ids). - -* **When to use**: - When you need to further process the Map-Reduce index results by: - * Having a recursive Map-Reduce index operation, setting up indexes on top of the Artificial Documents. - * Setting up a RavenDB ETL Task on the Artificial Documents collection to a dedicated database on - a separate cluster for further processing, as well as other ongoing tasks such as: SQL ETL and Subscriptions. +import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; -* **Example**: - MonthlyProductSales/13770576973199715021 +export const supportedLanguages = ["csharp"]; + + + + diff --git a/versioned_docs/version-7.0/server/kb/_document-identifier-generation-csharp.mdx b/versioned_docs/version-7.0/server/kb/_document-identifier-generation-csharp.mdx new file mode 100644 index 0000000000..ad5efcd410 --- /dev/null +++ b/versioned_docs/version-7.0/server/kb/_document-identifier-generation-csharp.mdx @@ -0,0 +1,531 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import ContentFrame from '@site/src/components/ContentFrame'; +import Panel from '@site/src/components/Panel'; + + + +* A document identifier (document ID) is a unique string associated with a document. + It is globally unique in the scope of the database - no two documents in the same database can have the same ID. + +* This article focuses on the different **Document ID Types** available in RavenDB and when to use each one. + Additional explanation is available in [Working with document identifiers](../../client-api/document-identifiers/working-with-document-identifiers.mdx). + To create a document from the Studio, see [Create new document](../../studio/database/documents/create-new-document.mdx#create-new-document). + +* In this article: + * [Overview](../../server/kb/document-identifier-generation.mdx#overview) + * [ID types](../../server/kb/document-identifier-generation.mdx#id-types) + * [ID structure](../../server/kb/document-identifier-generation.mdx#id-structure) + * [ID limitations](../../server/kb/document-identifier-generation.mdx#id-limitations) + * [Document IDs:](../../server/kb/document-identifier-generation.mdx#document-ids) + * [Semantic ID](../../server/kb/document-identifier-generation.mdx#semantic-id) + * [GUID](../../server/kb/document-identifier-generation.mdx#guid) + * [Server-side ID](../../server/kb/document-identifier-generation.mdx#server-side-id) + * [Identity ID](../../server/kb/document-identifier-generation.mdx#identity-id) + * [HiLo algorithm ID](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + * [Artificial document ID](../../server/kb/document-identifier-generation.mdx#artificial-document-id) + * [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character) + + + + + + +### ID types + +RavenDB supports several document ID types, where the ID string can be generated in different ways: + +* **Defined by the user**: + You explicitly specify the document ID. + * [Semantic ID](../../server/kb/document-identifier-generation.mdx#semantic-id) + +* **Generated by the server**: + The server generates the document ID based on the ID string format you provide when creating the document. + * [GUID](../../server/kb/document-identifier-generation.mdx#guid) + * [Server-side ID](../../server/kb/document-identifier-generation.mdx#server-side-id) + * [Identity ID](../../server/kb/document-identifier-generation.mdx#identity-id) + +* **Generated by the client (from a range provided by the server)**: + The server assigns a range of IDs to the client upon request. + The client then uses that range to generate document IDs locally within the session. + * [HiLo algorithm ID](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + +* **Generated from a Map-Reduce index output**: + The ID is generated by the server when saving map-reduce results as artificial documents. + * [Artificial document ID](../../server/kb/document-identifier-generation.mdx#artificial-document-id) + + + + +### ID Structure + +Document IDs typically consist of three parts: +the collection prefix, a slash (_'/'_) as the default separator, and a unique suffix. +For example: `users/123-A` (HiLo ID), or `users/000000000001-A` (Server-side ID). + +This structure is common but not mandatory: + * RavenDB does not require the ID to include a collection prefix. + * The default slash separator (`/`) can be **customized** for [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) + and [Identity IDs](../../server/kb/document-identifier-generation.mdx#identity-id). => see how below.... + + + + +### ID Limitations + +The following limitations apply to document IDs: + +* Maximum length: `512` bytes (in UTF-8) +* Document IDs cannot end with the following reserved characters: + * `/` - reserved for [Server-side ID generation](../../server/kb/document-identifier-generation.mdx#server-side-id) + * `|` - reserved for [Identity ID generation](../../server/kb/document-identifier-generation.mdx#identity-id) + + + + +## Document IDs: + + + +* **Generated by**: + The user + +* **Description**: + * The **semantic ID** is assigned by _you_ when creating the document (using the Client API or from the Studio), + and not generated by the server. It’s therefore your responsibility to ensure that each ID is unique. + * Creating a new document with an existing semantic ID will _overwrite_ the existing document. + +* **When to use**: + Use a semantic ID when you want the document’s identifier to convey meaning, + to reflect what the document represents. + +* **Example**: + * Documents that use an _email_ address as a unique identifier in the _Users_ collection: + * `users/ayende@ayende.com` + * `users/john@john.doe` + This makes the ID both globally unique and instantly meaningful. + It is clear which user the document represents. + * IDs that describe the document’s contents: + * `accounts/591-192/txs/2025-11-12` + Implying that the document holds all the transactions for account 591-192 on November 12th, 2025. + * `support-tickets/INV-88411` + A support ticket related to invoice 88411. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Specify the semantic ID in the entity's Id property + var user = new User { Name = "John", Id = "users/john@john.doe" }; + session.Store(user); + + session.SaveChanges(); + // The document will be saved with the ID you specified: "users/john@john.doe" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify the semantic ID when calling Store() + session.Store(user, "users/john@john.doe"); + + session.SaveChanges(); + // The document will be saved with the ID you specified: "users/john@john.doe" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * If you don’t specify a document ID when creating the document, + the server will generate a **globally unique identifier** (GUID) for the new document. + * Although this is a simple way to generate a document ID, GUIDs are not human-friendly + and make debugging or troubleshooting more difficult. This approach is generally less recommended. + +* **When to use**: + Use this only when you don’t care about the document ID and don’t need to trace it in logs, tools, or support. + +* **Example**: + A GUID as a document ID: + `50bbe329-6258-4634-be24-2f013d7174cd` + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to string.Empty + var user = new User { Name = "John", Id = string.Empty }; + session.Store(user); + + session.SaveChanges(); + // The server will generate a GUID-based ID, e.g. "50bbe329-6258-4634-be24-2f013d7174cd" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify string.Empty when calling Store() + session.Store(user, string.Empty); + + session.SaveChanges(); + // The server will generate a GUID-based ID, e.g. "50bbe329-6258-4634-be24-2f013d7174cd" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * When you create a document and provide an ID string that ends with a _slash_ (`/`), + the server will generate the full document ID for you. + * The server handling the request increments its [last document etag](../../glossary/etag.mdx) and appends it, + along with the **server's node tag**, to the string you provided. + * Since the _etag_ reflects any document change (add, update, delete), + the generated server-side IDs are always increasing but not guaranteed to be sequential. + +* **When to use**: + * Use the server-side ID when you don't care about the exact ID given to a newly created document. + * Recommended when creating many documents (e.g., during bulk insert), + as this method has the least overhead and requires minimal work from the server. + +* **Example**: + * On a server running on node 'A': + * Creating the first document with `users/` => results in document ID: `users/0000000000000000001-A` + * Creating a second document with `users/` => results in document ID: `users/0000000000000000002-A` + * On a server running on node 'B': + * Creating a third document with `users/` => may result in: `users/0000000000000000034-B` + * Note: node tag 'B' was appended to the ID generated because the request was handled by node 'B'. + Since each server has its own local _etag_, the numeric part of the ID is _not_ necessarily sequential (or unique) across the nodes + in the database group, as can happen when documents are created in parallel on multiple nodes during network partitions or failover. + +* **Note**: + If you _manually_ generate a document ID with a pattern that matches the server-side generated IDs, + RavenDB will _not_ check for that and will overwrite the existing document. + The leading zeros in server-side generated IDs help reduce the risk of such accidental collisions. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to "users/" + var user = new User { Name = "John", Id = "users/" }; + session.Store(user); + + session.SaveChanges(); + // The server will generate a server-side ID, e.g. "users/0000000000000000001-A" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify "users/" when calling Store() + session.Store(user, "users/"); + + session.SaveChanges(); + // The server will generate a server-side ID, e.g. "users/0000000000000000001-A" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * When you create a document and provide an ID string that ends with a _pipe_ symbol (`|`), + the server will generate an **identity** ID. + * The server replaces the _pipe_ with a separator character (_slash_ (`/`) by default) and appends + an always-incrementing number. + * Unlike the server-side ID, identity numbers are guaranteed to be **globally unique** across all nodes + in the database group. + +* **When to use**: + Use an identity ID only if you truly need document IDs that are incrementing. + For example, when generating invoice numbers or to meet legal or business requirements. + + Using an identity guarantees that IDs will increment, but doesn't guarantee that the sequence will be gapless. + Gaps may occur if documents are deleted or if a transaction fails after incrementing the counter. + For example: `companies/1`, `companies/2`, `companies/4`... + + +* **Example**: + * On a server running on node 'A': + * Creating the first document with `users|` => results in document ID: `users/1` + * Creating a second document with `users|` => results in document ID: `users/2` + * On a server running on node 'B': + * Creating a third document with `users|` => results in document ID: `users/3` + +* **Note**: + * Identity ID generation comes with a real cost. + In a cluster, where the database is replicated across multiple nodes, + the nodes must coordinate to ensure the same identity ID isn’t generated on two nodes. + This coordination requires network round-trips. + + * Moreover, if the server cannot reach the majority of nodes in the database group, + saving the document will fail because the next identity value cannot be generated. + + * All other ID generation methods continue to work even when the server is disconnected from the cluster. + So unless you specifically require incremental IDs, it’s better to use a different ID generation strategy. + +* **Customizing the separator character**: + The separator character used in the identity IDs can be customized. + Learn more in [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + +* **Customizing the identity number**: + The numeric part of an identity ID is an always-incrementing value managed by the server. + You can modify the latest identity number used for a given prefix (typically a collection name) in the following ways. + The server will base the next generated identity ID on the updated value you provide. + * **From the Client API**: + Use the [NextIdentityForOperation](../../client-api/operations/maintenance/identities/increment-next-identity.mdx) to increment the latest identity number. + Use the [SeedIdentityForOperation](../../client-api/operations/maintenance/identities/seed-identity.mdx) to explicitly set its starting value. + * **From the Studio**: + Go to the [Identities view](../../studio/database/documents/identities-view.mdx) to view or edit the latest identity number for any prefix. + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Set the entity's Id to "users|" + var user = new User { Name = "John", Id = "users|" }; + session.Store(user); + + session.SaveChanges(); + // The server will generate an identity ID, e.g. "users/1" +} +``` + + +```csharp +using (var session = store.OpenSession()) +{ + var user = new User { Name = "John" }; + // Specify "users|" when calling Store() + session.Store(user, "users|"); + + session.SaveChanges(); + // The server will generate an identity ID, e.g. "users/1" +} +``` + + + + + + +* **Generated by**: + The client (from a range provided by the server) + +* **Description**: + * The HiLo algorithm allows generating document IDs on the **client side**. + * The client requests a range of IDs from the server, + and the server ensures that this range is reserved exclusively for that client. + * Different clients receive different, non-overlapping ranges. + * The client can then safely generate IDs locally within the given range, + without further coordination with the server. + * For a more detailed explanation, see [HiLo Algorithm](../../client-api/document-identifiers/hilo-algorithm.mdx). + +* **When to use**: + Use HiLo when you want to create a document and immediately use its ID within the same transaction, + without needing an additional server call to fetch the ID. + +* **Example**: + `people/128-A`, `people/129-B` + +* **Customizing the separator character**: + The separator character used in the HiLo document IDs can be customized. + Learn more in [Customizing the separator character](../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + +--- + + + +```csharp +using (var session = store.OpenSession()) +{ + // Do not set the Id property of the entity + var user = new User { Name = "John" }; + + // Pass only the entity to Store(), without specifying an ID + session.Store(user); + + // The ID is already available here because the client holds a reserved range from the server + var documentId = user.Id; + + session.SaveChanges(); + // The document will be saved with the ID assigned by the session, e.g. "users/1-A" +} +``` + + + + + + +* **Generated by**: + The server + +* **Description**: + * The output of a Map-Reduce index can be saved as artificial documents in a new collection. + * Their IDs are generated automatically by the server. + Each ID consists of a prefix, which is the name of the output collection you specify, + followed by a hash of the _reduce_ key that you cannot control. + * For a more detailed explanation, see [Artificial Documents](../../indexes/map-reduce-indexes.mdx#reduce-results-as-artificial-documents). + +* **When to use**: + Use artificial documents when you need to further process Map-Reduce index results, for example: + * Creating a recursive Map-Reduce index over the resulting artificial documents. + * Running ETL tasks or Subscriptions on the resulting artificial documents collection for further processing. + +* **Example**: + `MonthlyProductSales/1377/0576973199715021` + + + + + +The separator character used in the [Identity](../../server/kb/document-identifier-generation.mdx#identity-id) +and [HiLo](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id) document IDs can be customized. +By default, the separator is a _slash_ (`/`), but this can be changed to any other character, except _pipe_ (`|`). + +There are several ways to customize the separator. +It can be configured globally for all databases (server-wide), or per database, overriding the global setting. + +--- + +### From the Studio: + +* Configure the separator character globally in: [Client configuration (server-wide)](../../studio/server/client-configuration.mdx). +* Override the global setting for a specific database in: [Client configuration (per database)](../../studio/database/settings/client-configuration-per-database.mdx). +* This will apply to both **Identity** & **HiLo** IDs. + +--- + +### From the Client API - using operations: + +* Set the separator globally using the [PutServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/put-serverwide-client-configuration.mdx). +* Override the global setting for a specific database using the [PutClientConfigurationOperation](../../client-api/operations/maintenance/configuration/put-client-configuration.mdx). +* This will apply to both **Identity** & **HiLo** IDs. + + +```csharp +// For example, set the separator character for a specific database + +var store = new DocumentStore +{ + Urls = new[] { "http://localhost:8080" }, + Database = "SampleDB" +}.Initialize(); + +// Customize the separator character to '#' instead of the default '/' +// using the 'PutClientConfigurationOperation' operation + store.Maintenance.Send(new PutClientConfigurationOperation( + new ClientConfiguration { IdentityPartsSeparator = '#' }));; + +using (var session = store.OpenSession()) +{ + // Create document - HiLo ID + // ========================= + var user1 = new User() { Name = "John" }; + session.Store(user1); + + // The session assigns the id immediately + var id = user1.Id; // "users#1-A" + + session.SaveChanges(); + // The document is saved with ID: "users#1-A" + + // Create document - Identity ID + // ============================= + var user2 = new User() { Name = "Jane" }; + session.Store(user2, "users|"); + + session.SaveChanges(); + // The document is saved with ID: "users#1" +} +``` + + +--- + +## From the Client API - using conventions: + +* For HiLo IDs, you can also set the separator character using the [IdentityPartsSeparator convention](../../client-api/configuration/conventions.mdx#identitypartsseparator) + on the _DocumentStore_ during initialization. +* Note: Any separator configured later via an operation or from the Studio will override this convention. +* This **applies only to HiLo IDs** and has no effect on Identity IDs. + + +```csharp +// Set the separator character for HiLo ID via conventions +var store = new DocumentStore +{ + Urls = new[] { "http://localhost:8080" }, + Database = "SampleDB", + Conventions = new DocumentConventions + { + IdentityPartsSeparator = '$', + // ... set any other conventions as needed + } +}.Initialize(); + +using (var session = store.OpenSession()) +{ + // Create document - HiLo ID + // ========================= + var user1 = new User() { Name = "John" }; + session.Store(user1); + + // The session assigns the id immediately + var id = user1.Id; // "users$1-A" + + session.SaveChanges(); + // The document is saved with ID: "users$1-A" + + // Create document - Identity ID + // ============================= + var user2 = new User() { Name = "Jane" }; + session.Store(user2, "users|"); + + session.SaveChanges(); + // The document is saved with ID: "users/1" (uses default separator '/') +} +``` + + \ No newline at end of file diff --git a/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx b/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx index 37de63e9c2..c3536cff00 100644 --- a/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx +++ b/versioned_docs/version-7.0/server/kb/document-identifier-generation.mdx @@ -1,284 +1,20 @@ ---- -title: "Knowledge Base: Document Identifier Generation" +--- +title: "Document Identifier Generation" hide_table_of_contents: true -sidebar_label: Document Identifier Generation +sidebar_label: "Document Identifier Generation" sidebar_position: 0 --- -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Knowledge Base: Document Identifier Generation - - -* A **Document Identifier**, `ID` in short, is a unique identification string associated with the document. - IDs are globally unique in the scope of the database: no two documents in the same - database will have the same ID. - -* IDs can be generated using different [strategies](../../server/kb/document-identifier-generation.mdx#id-generation-strategies): - by **a client**, by **the server**, by **client-server collaboratoin**, - or by a **map-reduce index output**. - -* In this page: - * [Document IDs](../../server/kb/document-identifier-generation.mdx#document-ids) - * [ID Generation Strategies](../../server/kb/document-identifier-generation.mdx#id-generation-strategies) - * [ID Structure](../../server/kb/document-identifier-generation.mdx#id-structure) - * [ID Limitations](../../server/kb/document-identifier-generation.mdx#id-limitations) - * [ID Generation by Client](../../server/kb/document-identifier-generation.mdx#id-generation-by-client) - * [Strategy: `Semantic ID`](../../server/kb/document-identifier-generation.mdx#strategy-) - * [ID Generation by Server](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) - * [Strategy: `GUID`](../../server/kb/document-identifier-generation.mdx#strategy--1) - * [Strategy: `Server-Side ID`](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Strategy: `Identity`](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [ID Generation by Client-Server Collaboration](../../server/kb/document-identifier-generation.mdx#id-generation-by-client-server-collaboration) - * [Strategy: `HiLo Algorithm`](../../server/kb/document-identifier-generation.mdx#strategy--4) - * [ID Generation by Map-Reduce Index Output](../../server/kb/document-identifier-generation.mdx#id-generation-by-map-reduce-index-output) - * [Strategy: `Artificial Document ID`](../../server/kb/document-identifier-generation.mdx#strategy--5) - - -## Document IDs - -### ID Generation Strategies - -Document identifiers can be generated using the following strategies: -Click a strategy to read more about its implementation. - -* By [a Client](../../server/kb/document-identifier-generation.mdx#id-generation-by-client) -* By [the Server](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) -* By [Client-Server Collaboratoin](../../server/kb/document-identifier-generation.mdx#id-generation-by-client-server-collaboration) -* By [Map-Reduce Index Output](../../server/kb/document-identifier-generation.mdx#id-generation-by-map-reduce-index-output) -### ID Structure - -The document ID is typiclly composed of the collection name as prefix, a slash (`/`), and the unique ID portion -(including a node tag, e.g. `A`, indicating which server node the document resides on). -E.g.: `users/1-A` - -Note that this behavior is **not** mandatory: - -* RavenDB does not require the collection prefix to be included in the ID string. -* The [Identifier Parts Separator](../../server/kb/document-identifier-generation.mdx#id-generation-by-server) can be replaced. -### ID Limitations - -The following limitations apply to document IDs: - -* Identifiers length limit: **512 bytes** (in UTF8) -* Identifiers cannot end with the following reserved characters: - `/` (reserved for Server-Side ID) - `|` (reserved for Identity generation) - - - -## ID Generation by Client -### Strategy: `Semantic ID` - -* **Generated by**: - The user - -* **Description**: - * The **semantic ID** is generated by _the user_ (using the Client API or from the Studio) and not by RavenDB server. - As such, it is the user's responsibility to generate unique IDs. - * Creating a new document with an existing semantic ID will _overwrite_ the existing document. - -* **When to use**: - Use a semantic ID when you want the document to have an identifier that has some meaningful value. - -* **Example**: - * Documents with a unique semantic ID containing a user's _email_ can be generated under the 'Users' collection: - * users/ayende@ayende.com - * users/john@john.doe - * For clarity, the document content can be indicated within the Semantic ID string: - * accounts/591-192/txs/2017-05-17 - Implying that the document holds all the transactions from May 17th, 2017 for account 591-192 - - -## ID Generation by Server - - -By default, the components of document IDs created by the server are separated by the `/` character. -This default separator can be replaced with any other character except `|` -in the [Document Store Conventions](../../client-api/configuration/conventions.mdx#changing-the-identity-separator). - -Examples: - - - - -{`// Change the ID separator from the default \`/\` to \`-\` -store.Maintenance.Send( - new PutClientConfigurationOperation( - new ClientConfiguration { IdentityPartsSeparator = '-' })); - -using (var session = store.OpenSession()) -{ - // The \`|\` causes the cluster to generate an identity - // The ID is unique over the whole cluster - // The first generated ID will be \`Prefix-1\` - session.Store(new User - { - Name = "John", - Id = "Prefix|" - }); - - session.SaveChanges(); -} -`} - - - - -{`// Change the ID separator from the default \`/\` to \`-\` -store.Maintenance.Send( - new PutClientConfigurationOperation( - new ClientConfiguration { IdentityPartsSeparator = '-' })); - -using (var session = store.OpenSession()) -{ - // Since an ID wasn't explicitly provided, the server generates one. - // The first generated ID on node A will be \`users-1-A\` - session.Store(new User - { - Name = "John", - }); - - session.SaveChanges(); -} -`} - - - - - -### Strategy: `Guid` - -* **Generated by**: - The server - -* **Description**: - * When a document ID is _not_ specified, RavenDB server will generate a **globally unique identifier** (GUID) for the stored new document. - * Although this is the simplest way to generate a document ID, Guids are _not_ human-friendly when it comes to debugging or troubleshooting - and are less recommended. - -* **When to use**: - Only When you don't care about the exact ID generated and about the ease of troubleshooting your app... -### Strategy: `Server-Side ID` - -* **Generated by**: - The server - -* **Description**: - * Upon document creation, providing a document ID string that ends with a _slash_ ( / ) will cause the server to generate a **server-side ID**. - * The RavenDB server that is handling the request will increment the value of its [Last Document Etag](../../glossary/etag.mdx). - This _Etag_ and the _Server Node Tag_ are appended by the server to the end of the ID string provided. - * Since the etag on which the ID is based changes upon any adding, deleting, or updating a document, - the only guarantee about the Server-Side ID is that it is always increasing, but not always sequential. - -* **When to use**: - * Use the server-side ID when you don't care about the exact ID that is given to a newly created document. - * Recommended when a large number of documents are needed to be created, such as in bulk insert scenarios, - as this method requires the least amount of work from RavenDB. - -* **Example**: - * From a server running on node 'A': - * Creating the first document with 'users/' => will result with document ID: _'users/0000000000000000001-A'_ - * Creating a second document with 'users/' => will result with document ID: _'users/0000000000000000002-A'_ - * From a server running on node 'B': - * Creating a third document with 'users/' => can result for example with document ID: _'users/0000000000000000034-B'_ - * Note: node tag 'B' was appended to the ID generated, as the server handling the request is on node 'B'. - But, since each server has its own local Etag, the numeric part in the ID will _not_ necessarily be sequential (or unique) across the nodes - within the database group in the cluster, as can happen when creating documents at partition time. - -* **Note**: - If you _manually_ generate a document ID with a pattern that matches the server-side generated IDs, - RavenDB will _not_ check for that and will overwrite the existing document. - The leading zeros help avoid such conflicts with any existing document by accident. -### Strategy: `Identity` - -* **Generated by**: - The server - -* **Description**: - * Upon document creation, providing a document ID string that ends with a _pipe symbol_ (`|`) will cause the server to generate an **identity**. - * RavenDb will create a simple, always-incrementing value and append it to the ID string provided (replacing the pipe with a slash). - * As opposed to the Server-Side ID, This value _will be unique_ across all the nodes within the Database Group in the cluster. - -* **When to use**: - Use an identity only if you really need documents with incremental IDs, - i.e. when generating invoices, or upon legal obligation. - - Using an identity guarantees that IDs will be incremental, but does **not** guarantee - that there wouldn't be gaps in the sequence. - The IDs sequence can therefore be, for example, `companies/1`, `companies/2`, `companies/4`.. - This is because - - - * Documents could have been deleted. - * A failed transaction still increments the identity value, thus causing a gap in the sequence. - - - -* **Example**: - * From a server running on node 'A': - * Creating the first document with 'users|' => will result with document ID: _'users/1'_ - * Creating a second document with 'users|' => will result with document ID: _'users/2'_ - * From a server running on node 'B': - * Creating a third document with 'users|' => will result with document ID: _'users/3'_ - -* **Note**: - * Identity has a real cost associated with it. - Generating identities in a cluster where the database is replicated across more than one node requires a lot of work. - * Network round trips are required as the nodes must coordinate with one another so that the same identity is _not_ generated on 2 different nodes in the cluster. - * Moreover, upon a failure scenario, if the node cannot communicate with the other cluster members, or the majority of nodes cannot be communicated with, - saving the document will fail as the requested identity cannot be generated. - * All the other ID generation methods can work without any issue when the server is disconnected from the cluster, - so unless you truly need incremental IDs, use one of the other options. - - - -## ID Generation by Client-Server Collaboration -### Strategy: `HiLo Algorithm` - -* **Generated by**: - Both the server and the client - -* **Description**: - * The Hilo algorithm enables generating document IDs on the client. - * The client reserves a range of identifiers from the server and the server ensures that this range will be provided only to this client. - * Different clients will receive different ranges. - * Each client can then safely generate identifiers within the range it was given, no further coordination with the server is required. - * For a more detailed explanation see [HiLo Algorithm](../../client-api/document-identifiers/hilo-algorithm.mdx) - -* **When to use**: - When you want to write code on the client that will create a new document and use its ID immediately in the same transaction, - without making another call to the server to get the ID and use it in a separate transaction. - -* **Example**: - people/128-A, people/129-B - - - -## ID Generation by Map-Reduce Index Output -### Strategy: `Artificial Document ID` - -* **Generated by**: - The server - -* **Description**: - * The output from a Map-Reduce index can be saved as Artificial Documents in a new collection. - * You have no control over these artificial documetns IDs, they are generated by RavenDB based on the hash of the reduce key. - * For a more detailed explanation see [Artificial Documents](../../indexes/map-reduce-indexes.mdx#reduce-results-as-artificial-documents) - abd the creation of their [IDs](../../indexes/map-reduce-indexes.mdx#ids). - -* **When to use**: - When you need to further process the Map-Reduce index results by: - * Having a recursive Map-Reduce index operation, setting up indexes on top of the Artificial Documents. - * Setting up a RavenDB ETL Task on the Artificial Documents collection to a dedicated database on - a separate cluster for further processing, as well as other ongoing tasks such as: SQL ETL and Subscriptions. +import DocumentIDsCsharp from './_document-identifier-generation-csharp.mdx'; -* **Example**: - MonthlyProductSales/13770576973199715021 +export const supportedLanguages = ["csharp"]; + + + + From 8c3c8c2a1f5f2e00bac341ecaa21e6cde823160d Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 16 Nov 2025 12:08:34 +0200 Subject: [PATCH 3/7] RDoc-3570 Fix desc of IdentityPartsSeparator in the conventions (C# & Node.js, v7.1) --- .../configuration/_conventions-csharp.mdx | 14 ++++++-------- .../configuration/_conventions-nodejs.mdx | 18 ++++++++---------- 2 files changed, 14 insertions(+), 18 deletions(-) diff --git a/docs/client-api/configuration/_conventions-csharp.mdx b/docs/client-api/configuration/_conventions-csharp.mdx index 4a4bd10391..5889ddc81c 100644 --- a/docs/client-api/configuration/_conventions-csharp.mdx +++ b/docs/client-api/configuration/_conventions-csharp.mdx @@ -750,16 +750,14 @@ public Version HttpVersion \{ get; set; \} #### IdentityPartsSeparator -* Use the `IdentityPartsSeparator` convention to set the default **ID separator** for automatically generated document IDs. +* Use the `IdentityPartsSeparator` convention to customize the **default ID separator** for document IDs generated automatically by the + [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm). -* DEFAULT: `/` (forward slash) - -* The value can be any `char` except `|` (pipe). +* The value can be any char except `|` (pipe), which is reserved for identity IDs. -* Changing the separator affects these ID generation strategies: - * [Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Identity](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [HiLo Algorithm](../../server/kb/document-identifier-generation.mdx#strategy--4) +* DEFAULT: `/` (forward slash) + +* Applies only to: [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). diff --git a/docs/client-api/configuration/_conventions-nodejs.mdx b/docs/client-api/configuration/_conventions-nodejs.mdx index 39bb5025c9..f5b81fa38a 100644 --- a/docs/client-api/configuration/_conventions-nodejs.mdx +++ b/docs/client-api/configuration/_conventions-nodejs.mdx @@ -219,16 +219,14 @@ set firstBroadcastAttemptTimeout(firstBroadcastAttemptTimeout); #### identityPartsSeparator -* Use the `identityPartsSeparator` convention to set the default **ID separator** for automatically-generated document IDs. - -* DEFAULT: `/` (forward slash) - -* The value can be any `char` except `|` (pipe). - -* Changing the separator affects these ID generation strategies: - * [Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Identity](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [HiLo Algorithm](../../server/kb/document-identifier-generation.mdx#strategy--4) +* Use the `identityPartsSeparator` convention to customize the **default ID separator** for document IDs generated automatically by the + [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm). + +* The value can be any char except `|` (pipe), which is reserved for identity IDs. + +* DEFAULT: `/` (forward slash) + +* Applies only to: [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). From 10d8f510cbefb8da80d12d5bfcd59cb9c5c3d37a Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 16 Nov 2025 12:12:01 +0200 Subject: [PATCH 4/7] RDoc-3570 Fix desc of IdentityPartsSeparator in the conventions (C# & Node.js, v7.0 v6.2) --- .../configuration/_conventions-csharp.mdx | 14 ++++++-------- .../configuration/_conventions-nodejs.mdx | 18 ++++++++---------- .../configuration/_conventions-csharp.mdx | 14 ++++++-------- .../configuration/_conventions-nodejs.mdx | 18 ++++++++---------- 4 files changed, 28 insertions(+), 36 deletions(-) diff --git a/versioned_docs/version-6.2/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/_conventions-csharp.mdx index aa9256acd0..de12a6e99e 100644 --- a/versioned_docs/version-6.2/client-api/configuration/_conventions-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/_conventions-csharp.mdx @@ -748,16 +748,14 @@ public Version HttpVersion \{ get; set; \} #### IdentityPartsSeparator -* Use the `IdentityPartsSeparator` convention to set the default **ID separator** for automatically-generated document IDs. +* Use the `IdentityPartsSeparator` convention to customize the **default ID separator** for document IDs generated automatically by the + [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm). -* DEFAULT: `/` (forward slash) - -* The value can be any `char` except `|` (pipe). +* The value can be any char except `|` (pipe), which is reserved for identity IDs. -* Changing the separator affects these ID generation strategies: - * [Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Identity](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [HiLo Algorithm](../../server/kb/document-identifier-generation.mdx#strategy--4) +* DEFAULT: `/` (forward slash) + +* Applies only to: [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). diff --git a/versioned_docs/version-6.2/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-6.2/client-api/configuration/_conventions-nodejs.mdx index 39bb5025c9..f5b81fa38a 100644 --- a/versioned_docs/version-6.2/client-api/configuration/_conventions-nodejs.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/_conventions-nodejs.mdx @@ -219,16 +219,14 @@ set firstBroadcastAttemptTimeout(firstBroadcastAttemptTimeout); #### identityPartsSeparator -* Use the `identityPartsSeparator` convention to set the default **ID separator** for automatically-generated document IDs. - -* DEFAULT: `/` (forward slash) - -* The value can be any `char` except `|` (pipe). - -* Changing the separator affects these ID generation strategies: - * [Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Identity](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [HiLo Algorithm](../../server/kb/document-identifier-generation.mdx#strategy--4) +* Use the `identityPartsSeparator` convention to customize the **default ID separator** for document IDs generated automatically by the + [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm). + +* The value can be any char except `|` (pipe), which is reserved for identity IDs. + +* DEFAULT: `/` (forward slash) + +* Applies only to: [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). diff --git a/versioned_docs/version-7.0/client-api/configuration/_conventions-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/_conventions-csharp.mdx index 4a4bd10391..5889ddc81c 100644 --- a/versioned_docs/version-7.0/client-api/configuration/_conventions-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/_conventions-csharp.mdx @@ -750,16 +750,14 @@ public Version HttpVersion \{ get; set; \} #### IdentityPartsSeparator -* Use the `IdentityPartsSeparator` convention to set the default **ID separator** for automatically generated document IDs. +* Use the `IdentityPartsSeparator` convention to customize the **default ID separator** for document IDs generated automatically by the + [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm). -* DEFAULT: `/` (forward slash) - -* The value can be any `char` except `|` (pipe). +* The value can be any char except `|` (pipe), which is reserved for identity IDs. -* Changing the separator affects these ID generation strategies: - * [Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Identity](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [HiLo Algorithm](../../server/kb/document-identifier-generation.mdx#strategy--4) +* DEFAULT: `/` (forward slash) + +* Applies only to: [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). diff --git a/versioned_docs/version-7.0/client-api/configuration/_conventions-nodejs.mdx b/versioned_docs/version-7.0/client-api/configuration/_conventions-nodejs.mdx index 39bb5025c9..f5b81fa38a 100644 --- a/versioned_docs/version-7.0/client-api/configuration/_conventions-nodejs.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/_conventions-nodejs.mdx @@ -219,16 +219,14 @@ set firstBroadcastAttemptTimeout(firstBroadcastAttemptTimeout); #### identityPartsSeparator -* Use the `identityPartsSeparator` convention to set the default **ID separator** for automatically-generated document IDs. - -* DEFAULT: `/` (forward slash) - -* The value can be any `char` except `|` (pipe). - -* Changing the separator affects these ID generation strategies: - * [Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2) - * [Identity](../../server/kb/document-identifier-generation.mdx#strategy--3) - * [HiLo Algorithm](../../server/kb/document-identifier-generation.mdx#strategy--4) +* Use the `identityPartsSeparator` convention to customize the **default ID separator** for document IDs generated automatically by the + [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm). + +* The value can be any char except `|` (pipe), which is reserved for identity IDs. + +* DEFAULT: `/` (forward slash) + +* Applies only to: [HiLo IDs](../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). From 81ac286cc67eeb6a153c60355368e774ca028dce Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 16 Nov 2025 13:04:43 +0200 Subject: [PATCH 5/7] RDoc-3570 Fix desc of IdentityPartsSepartor in the Identities View Studio article --- .../database/documents/identities-view.mdx | 48 ++++++++----------- .../database/documents/identities-view.mdx | 48 ++++++++----------- .../database/documents/identities-view.mdx | 48 ++++++++----------- 3 files changed, 63 insertions(+), 81 deletions(-) diff --git a/docs/studio/database/documents/identities-view.mdx b/docs/studio/database/documents/identities-view.mdx index 01dc678e62..600cc78afe 100644 --- a/docs/studio/database/documents/identities-view.mdx +++ b/docs/studio/database/documents/identities-view.mdx @@ -12,7 +12,6 @@ import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Identities View * This view lists the __latest identities values__ that are set on the server for all collections where @@ -22,37 +21,39 @@ import LanguageContent from "@site/src/components/LanguageContent"; * Identities values can also be managed from the Client API, see [seed identity operation](../../../client-api/operations/maintenance/identities/seed-identity.mdx). -* In this page: +* In this article: * [What is an identity](../../../studio/database/documents/identities-view.mdx#what-is-an-identity) * [The latest values](../../../studio/database/documents/identities-view.mdx#the-latest-values) * [Edit identity value](../../../studio/database/documents/identities-view.mdx#edit-identity-value) * [Add new identity](../../../studio/database/documents/identities-view.mdx#add-new-identity) + + ## What is an identity -* An identity is a document ID generated by the server upon document creation time - (when adding a pipe `|` as a suffix to the requested document ID). +* An identity is a document ID generated automatically by the server when you provide an ID that ends with + a pipe symbol (`|`) during document creation. -* The identity ID is __unique__ in the database, across all nodes within the Database Group. +* The identity ID is guaranteed to be **unique** in the database, across all nodes within the Database Group. -* The identity document ID is composed of: - * The collection name - * And a number that is continuously incremented per document creation ("the latest value") - e.g. `employees/5` +* The identity document ID (e.g., `employees/5`) is composed of: + * The collection name (_empolyees_) + * A separator chrarcter, slash (`/`) by default. + You can customize this character, see [Customizing the separator character](../../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + * A numeric value that is incremented per collection whenever a new identity document is created, + (_5_ in this example). * Learn more about identities in: - * [Document identifier generation](../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Document identifier generation - Identity ID](../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) - - ## The latest values ![Figure 1. Latest identities values](./assets/identities-view-1.png) -1. Navigate to __Documents > Identities__ +1. Navigate to **Documents > Identities** -2. __Document ID Prefix__ +2. **Document ID Prefix** * This string is the collection name for which an identity value was set: either [via this view](../../../studio/database/documents/identities-view.mdx#add-new-identity), @@ -60,7 +61,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * The string that shows is the collection name + a pipe suffix. -3. __Latest Value__ +3. **Latest Value** * This is the latest identity value currently set on the server for the collection. @@ -74,16 +75,14 @@ import LanguageContent from "@site/src/components/LanguageContent"; 5. Click to add a new identity value for another collection. - - ## Edit identity value ![Figure 2. Edit identity value](./assets/identities-view-2.png) -1. __Prefix__ +1. **Prefix** The collection for which the value is edited. -2. __Value__ +2. **Value** * Enter a number that will be set as the latest identity value for this collection. @@ -93,20 +92,18 @@ import LanguageContent from "@site/src/components/LanguageContent"; 3. Click 'Update' to set the new value. - - ## Add new identity ![Figure 3. Add new identity](./assets/identities-view-3.png) -1. __Prefix__ +1. **Prefix** * Enter the collection name for which to set an identity value. (Using the pipe suffix here is optional, e.g. can enter "users" or "users|"). * Note: you can specify a collection name that has not been created yet. -2. __Value__ +2. **Value** * Enter a number that will be set as the latest identity value for this collection. @@ -114,7 +111,4 @@ import LanguageContent from "@site/src/components/LanguageContent"; This means the next document that will be created with an identity in the _users_ collection will get the ID `users/100`. -3. Click 'Create' to create the new identity. - - - +3. Click 'Create' to create the new identity. \ No newline at end of file diff --git a/versioned_docs/version-6.2/studio/database/documents/identities-view.mdx b/versioned_docs/version-6.2/studio/database/documents/identities-view.mdx index 01dc678e62..600cc78afe 100644 --- a/versioned_docs/version-6.2/studio/database/documents/identities-view.mdx +++ b/versioned_docs/version-6.2/studio/database/documents/identities-view.mdx @@ -12,7 +12,6 @@ import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Identities View * This view lists the __latest identities values__ that are set on the server for all collections where @@ -22,37 +21,39 @@ import LanguageContent from "@site/src/components/LanguageContent"; * Identities values can also be managed from the Client API, see [seed identity operation](../../../client-api/operations/maintenance/identities/seed-identity.mdx). -* In this page: +* In this article: * [What is an identity](../../../studio/database/documents/identities-view.mdx#what-is-an-identity) * [The latest values](../../../studio/database/documents/identities-view.mdx#the-latest-values) * [Edit identity value](../../../studio/database/documents/identities-view.mdx#edit-identity-value) * [Add new identity](../../../studio/database/documents/identities-view.mdx#add-new-identity) + + ## What is an identity -* An identity is a document ID generated by the server upon document creation time - (when adding a pipe `|` as a suffix to the requested document ID). +* An identity is a document ID generated automatically by the server when you provide an ID that ends with + a pipe symbol (`|`) during document creation. -* The identity ID is __unique__ in the database, across all nodes within the Database Group. +* The identity ID is guaranteed to be **unique** in the database, across all nodes within the Database Group. -* The identity document ID is composed of: - * The collection name - * And a number that is continuously incremented per document creation ("the latest value") - e.g. `employees/5` +* The identity document ID (e.g., `employees/5`) is composed of: + * The collection name (_empolyees_) + * A separator chrarcter, slash (`/`) by default. + You can customize this character, see [Customizing the separator character](../../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + * A numeric value that is incremented per collection whenever a new identity document is created, + (_5_ in this example). * Learn more about identities in: - * [Document identifier generation](../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Document identifier generation - Identity ID](../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) - - ## The latest values ![Figure 1. Latest identities values](./assets/identities-view-1.png) -1. Navigate to __Documents > Identities__ +1. Navigate to **Documents > Identities** -2. __Document ID Prefix__ +2. **Document ID Prefix** * This string is the collection name for which an identity value was set: either [via this view](../../../studio/database/documents/identities-view.mdx#add-new-identity), @@ -60,7 +61,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * The string that shows is the collection name + a pipe suffix. -3. __Latest Value__ +3. **Latest Value** * This is the latest identity value currently set on the server for the collection. @@ -74,16 +75,14 @@ import LanguageContent from "@site/src/components/LanguageContent"; 5. Click to add a new identity value for another collection. - - ## Edit identity value ![Figure 2. Edit identity value](./assets/identities-view-2.png) -1. __Prefix__ +1. **Prefix** The collection for which the value is edited. -2. __Value__ +2. **Value** * Enter a number that will be set as the latest identity value for this collection. @@ -93,20 +92,18 @@ import LanguageContent from "@site/src/components/LanguageContent"; 3. Click 'Update' to set the new value. - - ## Add new identity ![Figure 3. Add new identity](./assets/identities-view-3.png) -1. __Prefix__ +1. **Prefix** * Enter the collection name for which to set an identity value. (Using the pipe suffix here is optional, e.g. can enter "users" or "users|"). * Note: you can specify a collection name that has not been created yet. -2. __Value__ +2. **Value** * Enter a number that will be set as the latest identity value for this collection. @@ -114,7 +111,4 @@ import LanguageContent from "@site/src/components/LanguageContent"; This means the next document that will be created with an identity in the _users_ collection will get the ID `users/100`. -3. Click 'Create' to create the new identity. - - - +3. Click 'Create' to create the new identity. \ No newline at end of file diff --git a/versioned_docs/version-7.0/studio/database/documents/identities-view.mdx b/versioned_docs/version-7.0/studio/database/documents/identities-view.mdx index 01dc678e62..600cc78afe 100644 --- a/versioned_docs/version-7.0/studio/database/documents/identities-view.mdx +++ b/versioned_docs/version-7.0/studio/database/documents/identities-view.mdx @@ -12,7 +12,6 @@ import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Identities View * This view lists the __latest identities values__ that are set on the server for all collections where @@ -22,37 +21,39 @@ import LanguageContent from "@site/src/components/LanguageContent"; * Identities values can also be managed from the Client API, see [seed identity operation](../../../client-api/operations/maintenance/identities/seed-identity.mdx). -* In this page: +* In this article: * [What is an identity](../../../studio/database/documents/identities-view.mdx#what-is-an-identity) * [The latest values](../../../studio/database/documents/identities-view.mdx#the-latest-values) * [Edit identity value](../../../studio/database/documents/identities-view.mdx#edit-identity-value) * [Add new identity](../../../studio/database/documents/identities-view.mdx#add-new-identity) + + ## What is an identity -* An identity is a document ID generated by the server upon document creation time - (when adding a pipe `|` as a suffix to the requested document ID). +* An identity is a document ID generated automatically by the server when you provide an ID that ends with + a pipe symbol (`|`) during document creation. -* The identity ID is __unique__ in the database, across all nodes within the Database Group. +* The identity ID is guaranteed to be **unique** in the database, across all nodes within the Database Group. -* The identity document ID is composed of: - * The collection name - * And a number that is continuously incremented per document creation ("the latest value") - e.g. `employees/5` +* The identity document ID (e.g., `employees/5`) is composed of: + * The collection name (_empolyees_) + * A separator chrarcter, slash (`/`) by default. + You can customize this character, see [Customizing the separator character](../../../server/kb/document-identifier-generation.mdx#customizing-the-separator-character). + * A numeric value that is incremented per collection whenever a new identity document is created, + (_5_ in this example). * Learn more about identities in: - * [Document identifier generation](../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Document identifier generation - Identity ID](../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) - - ## The latest values ![Figure 1. Latest identities values](./assets/identities-view-1.png) -1. Navigate to __Documents > Identities__ +1. Navigate to **Documents > Identities** -2. __Document ID Prefix__ +2. **Document ID Prefix** * This string is the collection name for which an identity value was set: either [via this view](../../../studio/database/documents/identities-view.mdx#add-new-identity), @@ -60,7 +61,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * The string that shows is the collection name + a pipe suffix. -3. __Latest Value__ +3. **Latest Value** * This is the latest identity value currently set on the server for the collection. @@ -74,16 +75,14 @@ import LanguageContent from "@site/src/components/LanguageContent"; 5. Click to add a new identity value for another collection. - - ## Edit identity value ![Figure 2. Edit identity value](./assets/identities-view-2.png) -1. __Prefix__ +1. **Prefix** The collection for which the value is edited. -2. __Value__ +2. **Value** * Enter a number that will be set as the latest identity value for this collection. @@ -93,20 +92,18 @@ import LanguageContent from "@site/src/components/LanguageContent"; 3. Click 'Update' to set the new value. - - ## Add new identity ![Figure 3. Add new identity](./assets/identities-view-3.png) -1. __Prefix__ +1. **Prefix** * Enter the collection name for which to set an identity value. (Using the pipe suffix here is optional, e.g. can enter "users" or "users|"). * Note: you can specify a collection name that has not been created yet. -2. __Value__ +2. **Value** * Enter a number that will be set as the latest identity value for this collection. @@ -114,7 +111,4 @@ import LanguageContent from "@site/src/components/LanguageContent"; This means the next document that will be created with an identity in the _users_ collection will get the ID `users/100`. -3. Click 'Create' to create the new identity. - - - +3. Click 'Create' to create the new identity. \ No newline at end of file From 4b30704f4ea407106da5e1e4f6181fe49e148523 Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 16 Nov 2025 13:39:03 +0200 Subject: [PATCH 6/7] RDoc-3570 Fix desc of IdentityPartsSepartor in the Put Configuration Operation article --- .../configuration/_put-client-configuration-csharp.mdx | 4 ++-- .../configuration/_put-client-configuration-nodejs.mdx | 4 ++-- .../configuration/_put-client-configuration-php.mdx | 4 ++-- .../configuration/_put-client-configuration-python.mdx | 4 ++-- .../configuration/_put-client-configuration-csharp.mdx | 4 ++-- .../configuration/_put-client-configuration-nodejs.mdx | 4 ++-- .../configuration/_put-client-configuration-php.mdx | 4 ++-- .../configuration/_put-client-configuration-python.mdx | 4 ++-- .../configuration/_put-client-configuration-csharp.mdx | 4 ++-- .../configuration/_put-client-configuration-nodejs.mdx | 4 ++-- .../configuration/_put-client-configuration-php.mdx | 4 ++-- .../configuration/_put-client-configuration-python.mdx | 4 ++-- 12 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx index 64798b4f00..df765bc1fa 100644 --- a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx +++ b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx index 536efc5c13..081a49d831 100644 --- a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx +++ b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx index af2b01bc5a..5064006839 100644 --- a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx +++ b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx index 3f28c09d2c..d20b190479 100644 --- a/docs/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx +++ b/docs/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx index 64798b4f00..df765bc1fa 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx index 536efc5c13..081a49d831 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx index af2b01bc5a..5064006839 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx index 3f28c09d2c..d20b190479 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx index 64798b4f00..df765bc1fa 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-csharp.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx index 536efc5c13..081a49d831 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-nodejs.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx index af2b01bc5a..5064006839 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-php.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx index 3f28c09d2c..d20b190479 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/configuration/_put-client-configuration-python.mdx @@ -57,8 +57,8 @@ import CodeBlock from '@theme/CodeBlock'; The following client configuration options are available: * **Identity parts separator**: - Set the separator used with automatically generated document identity IDs (default separator is `/`). - Learn more about identity IDs creation [here](../../../../server/kb/document-identifier-generation.mdx#strategy--3). + Set the separator used for automatically generated document IDs (default is `/`). + Applies only to [Identity IDs](../../../../server/kb/document-identifier-generation.mdx#identity-id) and [HiLo IDs](../../../../server/kb/document-identifier-generation.mdx#hilo-algorithm-id). * **Maximum number of requests per session**: Set this number to restrict the number of requests (Reads & Writes) per session in the client API. From 0b0b54ecdadcf2a5485638fdc7c20d1fc8edb040 Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 16 Nov 2025 14:02:52 +0200 Subject: [PATCH 7/7] RDoc-3570 Fix links --- .../maintenance/identities/_get-identities-csharp.mdx | 2 +- .../maintenance/identities/_get-identities-nodejs.mdx | 2 +- .../operations/maintenance/identities/_get-identities-php.mdx | 2 +- .../maintenance/identities/_get-identities-python.mdx | 2 +- .../operations/maintenance/identities/get-identities.mdx | 2 +- docs/server/kb/javascript-engine.mdx | 2 +- docs/server/ongoing-tasks/external-replication.mdx | 2 +- docs/server/ongoing-tasks/hub-sink-replication.mdx | 2 +- docs/studio/database/tasks/backup-task.mdx | 2 +- .../tasks/ongoing-tasks/hub-sink-replication/overview.mdx | 2 +- .../maintenance/identities/_get-identities-csharp.mdx | 2 +- .../maintenance/identities/_get-identities-nodejs.mdx | 2 +- .../operations/maintenance/identities/_get-identities-php.mdx | 2 +- .../maintenance/identities/_get-identities-python.mdx | 2 +- .../operations/maintenance/identities/get-identities.mdx | 2 +- versioned_docs/version-6.2/server/kb/javascript-engine.mdx | 4 ++-- .../version-6.2/server/ongoing-tasks/external-replication.mdx | 2 +- .../version-6.2/server/ongoing-tasks/hub-sink-replication.mdx | 2 +- .../version-6.2/studio/database/tasks/backup-task.mdx | 2 +- .../tasks/ongoing-tasks/hub-sink-replication/overview.mdx | 2 +- .../maintenance/identities/_get-identities-csharp.mdx | 2 +- .../maintenance/identities/_get-identities-nodejs.mdx | 2 +- .../operations/maintenance/identities/_get-identities-php.mdx | 2 +- .../maintenance/identities/_get-identities-python.mdx | 2 +- .../operations/maintenance/identities/get-identities.mdx | 2 +- versioned_docs/version-7.0/server/kb/javascript-engine.mdx | 2 +- .../version-7.0/server/ongoing-tasks/external-replication.mdx | 2 +- .../version-7.0/server/ongoing-tasks/hub-sink-replication.mdx | 2 +- .../version-7.0/studio/database/tasks/backup-task.mdx | 2 +- .../tasks/ongoing-tasks/hub-sink-replication/overview.mdx | 2 +- 30 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/docs/client-api/operations/maintenance/identities/_get-identities-csharp.mdx index 347b0ebe12..e1b4e99233 100644 --- a/docs/client-api/operations/maintenance/identities/_get-identities-csharp.mdx +++ b/docs/client-api/operations/maintenance/identities/_get-identities-csharp.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -* [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +* [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/docs/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx index fc1cb2cbd3..801b42934c 100644 --- a/docs/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx +++ b/docs/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -[Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +[Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * In this page: diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-php.mdx b/docs/client-api/operations/maintenance/identities/_get-identities-php.mdx index 5a8a06e441..a06083f2e1 100644 --- a/docs/client-api/operations/maintenance/identities/_get-identities-php.mdx +++ b/docs/client-api/operations/maintenance/identities/_get-identities-php.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -* [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +* [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) diff --git a/docs/client-api/operations/maintenance/identities/_get-identities-python.mdx b/docs/client-api/operations/maintenance/identities/_get-identities-python.mdx index f471a5ca3a..0887420d06 100644 --- a/docs/client-api/operations/maintenance/identities/_get-identities-python.mdx +++ b/docs/client-api/operations/maintenance/identities/_get-identities-python.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; * Learn more about identities in: - * [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) * In this page: diff --git a/docs/client-api/operations/maintenance/identities/get-identities.mdx b/docs/client-api/operations/maintenance/identities/get-identities.mdx index 8d401af4ee..7ae209fe63 100644 --- a/docs/client-api/operations/maintenance/identities/get-identities.mdx +++ b/docs/client-api/operations/maintenance/identities/get-identities.mdx @@ -46,7 +46,7 @@ export const supportedLanguages = ["csharp", "java", "python", "php", "nodejs"]; - [Type-specific ID Generation Conventions](../../../../client-api/configuration/identifier-generation/type-specific) ### Knowledge Base -- [Document Identifier Generation](../../../../server/kb/document-identifier-generation#strategy--3) +- [Document Identifier Generation](../../../../server/kb/document-identifier-generation.mdx#identity-id) - [Document Identifier Generation](../../../../server/kb/document-identifier-generation) ### Operations diff --git a/docs/server/kb/javascript-engine.mdx b/docs/server/kb/javascript-engine.mdx index 8fb355ae48..9a032a4a4b 100644 --- a/docs/server/kb/javascript-engine.mdx +++ b/docs/server/kb/javascript-engine.mdx @@ -69,7 +69,7 @@ RavenDB provides the following set of predefined functions: | **getMetadata(document)** | `object` | Returns the metadata of the specified document, including properties like `ChangeVector`, `ID`, and `LastModified`. | | **lastModified(document)** | `number` | Returns the number of milliseconds elapsed since the last modification time (UTC) of the specified document. | | **include(documentId)** | `Task` | Used in RQL [queries](../../client-api/session/querying/what-is-rql.mdx) to include the document with the specified ID with the results. | -| **put(documentId, document, [optional]changeVectorString)** | `Task` | Creates or updates a document with the specified ID.
To generate a new document ID, you can use the _"collectionPrefix/[Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2)"_ notation[[ex]](../../client-api/operations/patching/single-document.mdx#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document.mdx#clone-document). Used in patching. | +| **put(documentId, document, [optional]changeVectorString)** | `Task` | Creates or updates a document with the specified ID.
Learn about the different document identifiers in
[Document identifier generation](../../server/kb/document-identifier-generation.mdx)[[ex]](../../client-api/operations/patching/single-document.mdx#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document.mdx#clone-document). Used in patching. | | **del(documentId)** | `void` | Deletes the document with the specified ID.
Used in [patching](../../client-api/operations/patching/set-based.mdx#updating-a-collection-name). | | **archived.archiveAt(document, dateString)** | `void` | Schedules the specified document to be archived at the specified `dateString`.
Used in [patching](../../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). | | **archived.unarchive(document)** | `void` | Unarchives the specified document.
Used in [patching](../../data-archival/unarchiving-documents.mdx#unarchive-all-documents-in-a-collection---from-the-client-api). | diff --git a/docs/server/ongoing-tasks/external-replication.mdx b/docs/server/ongoing-tasks/external-replication.mdx index 8be5385088..9cba866038 100644 --- a/docs/server/ongoing-tasks/external-replication.mdx +++ b/docs/server/ongoing-tasks/external-replication.mdx @@ -57,7 +57,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * [Conflict resolution scripts](../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../studio/database/tasks/backup-task.mdx) diff --git a/docs/server/ongoing-tasks/hub-sink-replication.mdx b/docs/server/ongoing-tasks/hub-sink-replication.mdx index e6313ca0ab..422adbb597 100644 --- a/docs/server/ongoing-tasks/hub-sink-replication.mdx +++ b/docs/server/ongoing-tasks/hub-sink-replication.mdx @@ -74,7 +74,7 @@ After the data is in the destination server, setting up a hub/sink replication o * [Conflict resolver definitions](../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../studio/database/tasks/backup-task.mdx) diff --git a/docs/studio/database/tasks/backup-task.mdx b/docs/studio/database/tasks/backup-task.mdx index 021ff965b5..d8633bf13c 100644 --- a/docs/studio/database/tasks/backup-task.mdx +++ b/docs/studio/database/tasks/backup-task.mdx @@ -95,7 +95,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; 2. **Backup Task Type**: * **Backup** - * Backed Up Data: The database data in a JSON format, including documents, indexes (definitions only) & [identities](../../../server/kb/document-identifier-generation.mdx#strategy--3) + * Backed Up Data: The database data in a JSON format, including documents, indexes (definitions only) & [identities](../../../server/kb/document-identifier-generation.mdx#identity-id) (same as exported database format) * Size of backup data: Smaller * Backup Speed: Faster diff --git a/docs/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx b/docs/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx index 736da243d4..80761ad3dd 100644 --- a/docs/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx +++ b/docs/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx @@ -88,7 +88,7 @@ and Sink replication tasks. * [Conflict resolver definitions](../../../../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../../../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../../../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../../../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../../../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../../../../studio/database/tasks/backup-task.mdx) diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx index 347b0ebe12..e1b4e99233 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-csharp.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -* [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +* [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx index fc1cb2cbd3..801b42934c 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -[Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +[Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * In this page: diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-php.mdx index 5a8a06e441..9ab0c5b1cd 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-php.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-php.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -* [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +* [Document identifier generation -Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-python.mdx index f471a5ca3a..0887420d06 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-python.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/_get-identities-python.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; * Learn more about identities in: - * [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) * In this page: diff --git a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx index 8d401af4ee..7ae209fe63 100644 --- a/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-6.2/client-api/operations/maintenance/identities/get-identities.mdx @@ -46,7 +46,7 @@ export const supportedLanguages = ["csharp", "java", "python", "php", "nodejs"]; - [Type-specific ID Generation Conventions](../../../../client-api/configuration/identifier-generation/type-specific) ### Knowledge Base -- [Document Identifier Generation](../../../../server/kb/document-identifier-generation#strategy--3) +- [Document Identifier Generation](../../../../server/kb/document-identifier-generation.mdx#identity-id) - [Document Identifier Generation](../../../../server/kb/document-identifier-generation) ### Operations diff --git a/versioned_docs/version-6.2/server/kb/javascript-engine.mdx b/versioned_docs/version-6.2/server/kb/javascript-engine.mdx index 8780c35840..c766923622 100644 --- a/versioned_docs/version-6.2/server/kb/javascript-engine.mdx +++ b/versioned_docs/version-6.2/server/kb/javascript-engine.mdx @@ -69,7 +69,7 @@ RavenDB provides the following set of predefined functions: | **getMetadata(document)** | `object` | Returns the metadata of the specified document, including properties like `ChangeVector`, `ID`, and `LastModified`. | | **lastModified(document)** | `number` | Returns the number of milliseconds elapsed since the last modification time (UTC) of the specified document. | | **include(documentId)** | `Task` | Used in RQL [queries](../../client-api/session/querying/what-is-rql.mdx) to include the document with the specified ID with the results. | -| **put(documentId, document, [optional]changeVectorString)** | `Task` | Creates or updates a document with the specified ID.
To generate a new document ID, you can use the _"collectionPrefix/[Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2)"_ notation[[ex]](../../client-api/operations/patching/single-document.mdx#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document.mdx#clone-document). Used in patching. | +| **put(documentId, document, [optional]changeVectorString)** | `Task` | Creates or updates a document with the specified ID.
Learn about the different document identifiers in
[Document identifier generation](../../server/kb/document-identifier-generation.mdx)[[ex]](../../client-api/operations/patching/single-document.mdx#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document.mdx#clone-document). Used in patching. | | **del(documentId)** | `void` | Deletes the document with the specified ID.
Used in [patching](../../client-api/operations/patching/set-based.mdx#updating-a-collection-name). | | **archived.archiveAt(document, dateString)** | `void` | Schedules the specified document to be archived at the specified `dateString`.
Used in [patching](../../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). | | **archived.unarchive(document)** | `void` | Unarchives the specified document.
Used in [patching](../../data-archival/unarchiving-documents.mdx#unarchive-all-documents-in-a-collection---from-the-client-api). | @@ -131,4 +131,4 @@ RavenDB provides the following set of predefined functions: | Method Signature | Return | Description | |-------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------| -| **output(message)** or **console.log(message)** | `void` | Prints message to the debug output.
Used for debugging [single document patches](../../client-api/operations/patching/single-document.mdx). | +| **output(message)** or **console.log(message)** | `void` | Prints message to the debug output.
Used for debugging [single document patches](../../client-api/operations/patching/single-document.mdx). | diff --git a/versioned_docs/version-6.2/server/ongoing-tasks/external-replication.mdx b/versioned_docs/version-6.2/server/ongoing-tasks/external-replication.mdx index 8be5385088..9cba866038 100644 --- a/versioned_docs/version-6.2/server/ongoing-tasks/external-replication.mdx +++ b/versioned_docs/version-6.2/server/ongoing-tasks/external-replication.mdx @@ -57,7 +57,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * [Conflict resolution scripts](../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../studio/database/tasks/backup-task.mdx) diff --git a/versioned_docs/version-6.2/server/ongoing-tasks/hub-sink-replication.mdx b/versioned_docs/version-6.2/server/ongoing-tasks/hub-sink-replication.mdx index e6313ca0ab..422adbb597 100644 --- a/versioned_docs/version-6.2/server/ongoing-tasks/hub-sink-replication.mdx +++ b/versioned_docs/version-6.2/server/ongoing-tasks/hub-sink-replication.mdx @@ -74,7 +74,7 @@ After the data is in the destination server, setting up a hub/sink replication o * [Conflict resolver definitions](../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../studio/database/tasks/backup-task.mdx) diff --git a/versioned_docs/version-6.2/studio/database/tasks/backup-task.mdx b/versioned_docs/version-6.2/studio/database/tasks/backup-task.mdx index 021ff965b5..d8633bf13c 100644 --- a/versioned_docs/version-6.2/studio/database/tasks/backup-task.mdx +++ b/versioned_docs/version-6.2/studio/database/tasks/backup-task.mdx @@ -95,7 +95,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; 2. **Backup Task Type**: * **Backup** - * Backed Up Data: The database data in a JSON format, including documents, indexes (definitions only) & [identities](../../../server/kb/document-identifier-generation.mdx#strategy--3) + * Backed Up Data: The database data in a JSON format, including documents, indexes (definitions only) & [identities](../../../server/kb/document-identifier-generation.mdx#identity-id) (same as exported database format) * Size of backup data: Smaller * Backup Speed: Faster diff --git a/versioned_docs/version-6.2/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx b/versioned_docs/version-6.2/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx index 736da243d4..80761ad3dd 100644 --- a/versioned_docs/version-6.2/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx +++ b/versioned_docs/version-6.2/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx @@ -88,7 +88,7 @@ and Sink replication tasks. * [Conflict resolver definitions](../../../../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../../../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../../../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../../../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../../../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../../../../studio/database/tasks/backup-task.mdx) diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx index 347b0ebe12..e1b4e99233 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-csharp.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -* [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +* [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx index fc1cb2cbd3..801b42934c 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-nodejs.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -[Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +[Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * In this page: diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-php.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-php.mdx index 5a8a06e441..a06083f2e1 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-php.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-php.mdx @@ -19,7 +19,7 @@ import CodeBlock from '@theme/CodeBlock'; Learn more about identities in: -* [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) +* [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-python.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-python.mdx index f471a5ca3a..0887420d06 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-python.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/_get-identities-python.mdx @@ -18,7 +18,7 @@ import CodeBlock from '@theme/CodeBlock'; * Learn more about identities in: - * [Document identifier generation](../../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Document identifier generation - Identity ID](../../../../server/kb/document-identifier-generation.mdx#identity-id) * [Working with document identifiers](../../../../client-api/document-identifiers/working-with-document-identifiers.mdx#identities) * In this page: diff --git a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx index 8d401af4ee..80c3656c14 100644 --- a/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx +++ b/versioned_docs/version-7.0/client-api/operations/maintenance/identities/get-identities.mdx @@ -46,7 +46,7 @@ export const supportedLanguages = ["csharp", "java", "python", "php", "nodejs"]; - [Type-specific ID Generation Conventions](../../../../client-api/configuration/identifier-generation/type-specific) ### Knowledge Base -- [Document Identifier Generation](../../../../server/kb/document-identifier-generation#strategy--3) +- [Document Identifier Generation](../../../../server/kb/document-identifier-generation.mdx#identity-id3) - [Document Identifier Generation](../../../../server/kb/document-identifier-generation) ### Operations diff --git a/versioned_docs/version-7.0/server/kb/javascript-engine.mdx b/versioned_docs/version-7.0/server/kb/javascript-engine.mdx index 8fb355ae48..80b97d926d 100644 --- a/versioned_docs/version-7.0/server/kb/javascript-engine.mdx +++ b/versioned_docs/version-7.0/server/kb/javascript-engine.mdx @@ -69,7 +69,7 @@ RavenDB provides the following set of predefined functions: | **getMetadata(document)** | `object` | Returns the metadata of the specified document, including properties like `ChangeVector`, `ID`, and `LastModified`. | | **lastModified(document)** | `number` | Returns the number of milliseconds elapsed since the last modification time (UTC) of the specified document. | | **include(documentId)** | `Task` | Used in RQL [queries](../../client-api/session/querying/what-is-rql.mdx) to include the document with the specified ID with the results. | -| **put(documentId, document, [optional]changeVectorString)** | `Task` | Creates or updates a document with the specified ID.
To generate a new document ID, you can use the _"collectionPrefix/[Server-Side ID](../../server/kb/document-identifier-generation.mdx#strategy--2)"_ notation[[ex]](../../client-api/operations/patching/single-document.mdx#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document.mdx#clone-document). Used in patching. | +| **put(documentId, document, [optional]changeVectorString)** | `Task` | Creates or updates a document with the specified ID.
Learn about the different document identifiers in
[Document identifier generation](../../server/kb/document-identifier-generation.mdx)[[ex]](../../client-api/operations/patching/single-document.mdx#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document.mdx#clone-document). Used in patching. | | **del(documentId)** | `void` | Deletes the document with the specified ID.
Used in [patching](../../client-api/operations/patching/set-based.mdx#updating-a-collection-name). | | **archived.archiveAt(document, dateString)** | `void` | Schedules the specified document to be archived at the specified `dateString`.
Used in [patching](../../data-archival/schedule-document-archiving.mdx#schedule-multiple-documents-for-archiving---from-the-client-api). | | **archived.unarchive(document)** | `void` | Unarchives the specified document.
Used in [patching](../../data-archival/unarchiving-documents.mdx#unarchive-all-documents-in-a-collection---from-the-client-api). | diff --git a/versioned_docs/version-7.0/server/ongoing-tasks/external-replication.mdx b/versioned_docs/version-7.0/server/ongoing-tasks/external-replication.mdx index 8be5385088..9cba866038 100644 --- a/versioned_docs/version-7.0/server/ongoing-tasks/external-replication.mdx +++ b/versioned_docs/version-7.0/server/ongoing-tasks/external-replication.mdx @@ -57,7 +57,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * [Conflict resolution scripts](../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../studio/database/tasks/backup-task.mdx) diff --git a/versioned_docs/version-7.0/server/ongoing-tasks/hub-sink-replication.mdx b/versioned_docs/version-7.0/server/ongoing-tasks/hub-sink-replication.mdx index e6313ca0ab..422adbb597 100644 --- a/versioned_docs/version-7.0/server/ongoing-tasks/hub-sink-replication.mdx +++ b/versioned_docs/version-7.0/server/ongoing-tasks/hub-sink-replication.mdx @@ -74,7 +74,7 @@ After the data is in the destination server, setting up a hub/sink replication o * [Conflict resolver definitions](../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../studio/database/tasks/backup-task.mdx) diff --git a/versioned_docs/version-7.0/studio/database/tasks/backup-task.mdx b/versioned_docs/version-7.0/studio/database/tasks/backup-task.mdx index 021ff965b5..d8633bf13c 100644 --- a/versioned_docs/version-7.0/studio/database/tasks/backup-task.mdx +++ b/versioned_docs/version-7.0/studio/database/tasks/backup-task.mdx @@ -95,7 +95,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; 2. **Backup Task Type**: * **Backup** - * Backed Up Data: The database data in a JSON format, including documents, indexes (definitions only) & [identities](../../../server/kb/document-identifier-generation.mdx#strategy--3) + * Backed Up Data: The database data in a JSON format, including documents, indexes (definitions only) & [identities](../../../server/kb/document-identifier-generation.mdx#identity-id) (same as exported database format) * Size of backup data: Smaller * Backup Speed: Faster diff --git a/versioned_docs/version-7.0/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx b/versioned_docs/version-7.0/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx index 736da243d4..80761ad3dd 100644 --- a/versioned_docs/version-7.0/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx +++ b/versioned_docs/version-7.0/studio/database/tasks/ongoing-tasks/hub-sink-replication/overview.mdx @@ -88,7 +88,7 @@ and Sink replication tasks. * [Conflict resolver definitions](../../../../../server/clustering/replication/replication-conflicts.mdx#conflict-resolution-script) * [Compare-Exchange](../../../../../client-api/operations/compare-exchange/overview.mdx) * [Subscriptions](../../../../../client-api/data-subscriptions/what-are-data-subscriptions.mdx) - * [Identities](../../../../../server/kb/document-identifier-generation.mdx#strategy--3) + * [Identities](../../../../../server/kb/document-identifier-generation.mdx#identity-id) * Ongoing tasks * [ETL](../../../../../server/ongoing-tasks/etl/basics.mdx) * [Backup](../../../../../studio/database/tasks/backup-task.mdx)