{"action":"created","comment":{"url":"https://api.github.com/repos/ravendb/docs/pulls/comments/158773322","pull_request_review_id":85626800,"id":158773322,"diff_hunk":"@@ -0,0 +1,133 @@\n+# Working with document identifiers\n+\n+Each document in RavenDB database has a unique string associated with this document, called an identifier or a key. Every entity that you store either by using [a session](../session/what-is-a-session-and-how-does-it-work)\n+or with a [put doucment command](../commands/documents/put) will have such identity assigned in the database. In RavenDB there are [four options](../../server/kb/document-key-generation) supported by the server to store a document and assign an identifier to it.\n+The client can directly take advantage of them. You always can handling the key generation using the knowledge of the type of the entity and the identity number provided by the HiLo algorithm. This is how the identifier is generated by the session, which is described in details below.\n+\n+## Session usage\n+\n+If you choose to use the session, you don't have to pay any special attention to the identifiers of the stored entities. The session will take care of it by generating the keys automatically.\n+It utilizes [conventions](../../client-api/configuration/conventions/what-are-conventions) and HiLo algorithm to produce the identifiers. Everything is handled by the session's mechanism and is transparent for the user. \n+However, you can influence the key generation strategy by overwriting [the key generation conventions](../../client-api/configuration/conventions/identifier-generation/global). In this article we are going to consider the behavior \n+in accordance with the default conventions.\n+\n+{INFO:Identifiers in RavenDB are strings}\n+Identifiers of documents in RavenDB database are always strings. RavenDB is designed to work with string identifiers and that is the best option you should choose\n+when you model your entities.\n+{INFO/}\n+\n+\n+### Autogenerated ids\n+\n+In order to figure out which property (or field) holds the entity's identifier, the convention `Conventions.FindIdentityProperty` is called. \n+By default, it looks for the property or the field named `Id` (case sensitive). However this property can have `null` value or even not be present at all. Then the automatic key\n+generation strategy is performed. The default convention is that such entities get the keys in the following format `collection/number`. RavenDB client first determines\n+the name of [the collection](../../client-api/faq/what-is-a-collection) that the entity belongs to, and then contacts with the server in order to retrieve a numeric range of values, which can be used as the `number` part.\n+The range of available numbers is calculated by using `HiLo` algorithm and it is tracked per collection. The current maximum value in ranges are stored in documents `Raven/Hilo/collectionName`.\n+\n+Let's see the example.\n+\n+{CODE session_id_not_provided@ClientApi\\DocumentIdentifiers\\WorkingWithDocumentIds.cs /}\n+\n+What will be the identifier of this order? You can check it by calling:\n+\n+{CODE session_get_document_id@ClientApi\\DocumentIdentifiers\\WorkingWithDocumentIds.cs /}\n+\n+If this is the first `Order` entity in your database, then it will return `orders/1-A`. How does the key generation process proceed? The RavenDB client determines the collection name as `orders` (by default it is the plural form of the entity name).\n+Then it asks the server for the server to give him the id's range he can use (the first available range is 1 - 32), the server will handle the Raven/Hilo/orders document. \n+The next available identity value (always incrementing number) from the given range is `1` so its combination with the collection name and the node Id gives the result `orders/1-A`.\n+\n+The next attempt to store another `Order` object within the same session will result in creating the `orders/2-A` key. However, this time asking the server about the possible range\n+will not be necessary because the in-memory range (1 - 32) is enough, so simply the next number will be added as the key suffix.\n+\n+{INFO:Identity value numeric range generation}\n+Each (in code) document store _instance_ handles the generation of the identity value numeric range. The database stores the last requested number while the document store\n+_instances_ request ranges and caches the returned range of available identities.\n+\n+The database has a single document (per collection) which stores the last identity value requested by a document store instance.\n+Eg. the document `Raven/HiLo/accounts` has the following value `\n+{ \n+    \"Max\": \"4000\",\n+    \"@metadata\": {\n+        \"@collection\": \"@hilo\"\n+    } \n+}`, then the next range will be `4001 - 4032`, if 32 was range size. \n+(By default, it's 32).\n+\n+The number of sessions per document store instance play no part in identity value generation. When the session is close the client send to the server the max value that he use,\n+than the server will write it in the hilo document (If the Max number is bigger then the number from the client)\n+{INFO/}\n+\n+If your intention is to skip the key creation strategy that relays on the collection and HiLo value pair, then you can allow the RavenDB database to assign the Guid identifier\n+to the stored document. Then you have to provide the `string.Empty` as the value of the `Id` property:\n+\n+{CODE session_empty_string_id@ClientApi\\DocumentIdentifiers\\WorkingWithDocumentIds.cs /}\n+\n+Note that this time the check for the document id is called after `SaveChanges` because only then we go to the server while the entity's key are generated there.\n+\n+### Custom/semantic ids\n+\n+The session also supports the option to store the entity and explicitly tell under what identifier it should be stored in the database. To to this you can either set the `Id` property of the object:\n+\n+{CODE session_semantic_id_1@ClientApi\\DocumentIdentifiers\\WorkingWithDocumentIds.cs /}\n+\n+or use the following `Store` method overload:\n+\n+{CODE session_semantic_id_2@ClientApi\\DocumentIdentifiers\\WorkingWithDocumentIds.cs /}\n+\n+### Identity ids\n+\n+RavenDB also supports the notion of the identity without the usage of the HiLo. By creating a string Id property in your entity and setting it\n+to a value ending with a slash (`/`) and with a pipe (`|`), you can tell RavenDB to use that as a key prefix for your entity. That prefix followed by the next available integer identity value will \n+be your entity's key after calling `SaveChanges`. The identity value will be assigned by the server.\n+\n+{CODE session_identity_id@ClientApi\\DocumentIdentifiers\\WorkingWithDocumentIds.cs /}\n+\n+After execution of the above example, the first entity will get `companies/000000000000000001-A` key and the second one `companies/000000000000000002-A`. The identity values are stored per prefix. \n+Here, according to the default conventions, we used the collection name as the prefix. Note that we got the different results as we would if we used the the HiLo to auto-generate keys. if we want to get the same\n+result as in hilo we need to use the pipe symbol option. When you save a document whose ID ends with a pipe symbol, RavenDB will generate the ID for you. It will replace the pipe character with a slash (/) and\n+append a numeric value (the only guarantee you have about this value is that it's always increasing) and the node ID, the first entity will get `companies/1-A` key and the second one `companies/2-A`.","path":"Documentation/4.0/Raven.Documentation.Pages/client-api/document-identifiers/working-with-document-ids.markdown","position":89,"original_position":89,"commit_id":"1730143108d362e3bbe1278e6e4397c28df51237","original_commit_id":"1730143108d362e3bbe1278e6e4397c28df51237","user":{"login":"IdanHaim","id":10860984,"avatar_url":"https://avatars3.githubusercontent.com/u/10860984?v=4","gravatar_id":"","url":"https://api.github.com/users/IdanHaim","html_url":"https://github.com/IdanHaim","followers_url":"https://api.github.com/users/IdanHaim/followers","following_url":"https://api.github.com/users/IdanHaim/following{/other_user}","gists_url":"https://api.github.com/users/IdanHaim/gists{/gist_id}","starred_url":"https://api.github.com/users/IdanHaim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IdanHaim/subscriptions","organizations_url":"https://api.github.com/users/IdanHaim/orgs","repos_url":"https://api.github.com/users/IdanHaim/repos","events_url":"https://api.github.com/users/IdanHaim/events{/privacy}","received_events_url":"https://api.github.com/users/IdanHaim/received_events","type":"User","site_admin":false},"body":"I will try to rephrase","created_at":"2017-12-27T07:28:46Z","updated_at":"2017-12-27T07:28:46Z","html_url":"https://github.com/ravendb/docs/pull/434#discussion_r158773322","pull_request_url":"https://api.github.com/repos/ravendb/docs/pulls/434","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/ravendb/docs/pulls/comments/158773322"},"html":{"href":"https://github.com/ravendb/docs/pull/434#discussion_r158773322"},"pull_request":{"href":"https://api.github.com/repos/ravendb/docs/pulls/434"}},"in_reply_to_id":158743562},"pull_request":{"url":"https://api.github.com/repos/ravendb/docs/pulls/434","id":160147218,"html_url":"https://github.com/ravendb/docs/pull/434","diff_url":"https://github.com/ravendb/docs/pull/434.diff","patch_url":"https://github.com/ravendb/docs/pull/434.patch","issue_url":"https://api.github.com/repos/ravendb/docs/issues/434","number":434,"state":"open","locked":false,"title":"RDoc-871 Add working-with-document-ids, hilo-algorithm and handling-c…","user":{"login":"IdanHaim","id":10860984,"avatar_url":"https://avatars3.githubusercontent.com/u/10860984?v=4","gravatar_id":"","url":"https://api.github.com/users/IdanHaim","html_url":"https://github.com/IdanHaim","followers_url":"https://api.github.com/users/IdanHaim/followers","following_url":"https://api.github.com/users/IdanHaim/following{/other_user}","gists_url":"https://api.github.com/users/IdanHaim/gists{/gist_id}","starred_url":"https://api.github.com/users/IdanHaim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IdanHaim/subscriptions","organizations_url":"https://api.github.com/users/IdanHaim/orgs","repos_url":"https://api.github.com/users/IdanHaim/repos","events_url":"https://api.github.com/users/IdanHaim/events{/privacy}","received_events_url":"https://api.github.com/users/IdanHaim/received_events","type":"User","site_admin":false},"body":"…ase-sensitive-document-ids","created_at":"2017-12-26T16:39:51Z","updated_at":"2017-12-27T07:28:46Z","closed_at":null,"merged_at":null,"merge_commit_sha":"016dff698db8ac2b7dc10b57dcfaf957fac48762","assignee":null,"assignees":[],"requested_reviewers":[],"milestone":null,"commits_url":"https://api.github.com/repos/ravendb/docs/pulls/434/commits","review_comments_url":"https://api.github.com/repos/ravendb/docs/pulls/434/comments","review_comment_url":"https://api.github.com/repos/ravendb/docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ravendb/docs/issues/434/comments","statuses_url":"https://api.github.com/repos/ravendb/docs/statuses/1730143108d362e3bbe1278e6e4397c28df51237","head":{"label":"IdanHaim:RDoc-871","ref":"RDoc-871","sha":"1730143108d362e3bbe1278e6e4397c28df51237","user":{"login":"IdanHaim","id":10860984,"avatar_url":"https://avatars3.githubusercontent.com/u/10860984?v=4","gravatar_id":"","url":"https://api.github.com/users/IdanHaim","html_url":"https://github.com/IdanHaim","followers_url":"https://api.github.com/users/IdanHaim/followers","following_url":"https://api.github.com/users/IdanHaim/following{/other_user}","gists_url":"https://api.github.com/users/IdanHaim/gists{/gist_id}","starred_url":"https://api.github.com/users/IdanHaim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IdanHaim/subscriptions","organizations_url":"https://api.github.com/users/IdanHaim/orgs","repos_url":"https://api.github.com/users/IdanHaim/repos","events_url":"https://api.github.com/users/IdanHaim/events{/privacy}","received_events_url":"https://api.github.com/users/IdanHaim/received_events","type":"User","site_admin":false},"repo":{"id":65298293,"name":"docs","full_name":"IdanHaim/docs","owner":{"login":"IdanHaim","id":10860984,"avatar_url":"https://avatars3.githubusercontent.com/u/10860984?v=4","gravatar_id":"","url":"https://api.github.com/users/IdanHaim","html_url":"https://github.com/IdanHaim","followers_url":"https://api.github.com/users/IdanHaim/followers","following_url":"https://api.github.com/users/IdanHaim/following{/other_user}","gists_url":"https://api.github.com/users/IdanHaim/gists{/gist_id}","starred_url":"https://api.github.com/users/IdanHaim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IdanHaim/subscriptions","organizations_url":"https://api.github.com/users/IdanHaim/orgs","repos_url":"https://api.github.com/users/IdanHaim/repos","events_url":"https://api.github.com/users/IdanHaim/events{/privacy}","received_events_url":"https://api.github.com/users/IdanHaim/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/IdanHaim/docs","description":"Documenation book for RavenDB","fork":true,"url":"https://api.github.com/repos/IdanHaim/docs","forks_url":"https://api.github.com/repos/IdanHaim/docs/forks","keys_url":"https://api.github.com/repos/IdanHaim/docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/IdanHaim/docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/IdanHaim/docs/teams","hooks_url":"https://api.github.com/repos/IdanHaim/docs/hooks","issue_events_url":"https://api.github.com/repos/IdanHaim/docs/issues/events{/number}","events_url":"https://api.github.com/repos/IdanHaim/docs/events","assignees_url":"https://api.github.com/repos/IdanHaim/docs/assignees{/user}","branches_url":"https://api.github.com/repos/IdanHaim/docs/branches{/branch}","tags_url":"https://api.github.com/repos/IdanHaim/docs/tags","blobs_url":"https://api.github.com/repos/IdanHaim/docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/IdanHaim/docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/IdanHaim/docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/IdanHaim/docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/IdanHaim/docs/statuses/{sha}","languages_url":"https://api.github.com/repos/IdanHaim/docs/languages","stargazers_url":"https://api.github.com/repos/IdanHaim/docs/stargazers","contributors_url":"https://api.github.com/repos/IdanHaim/docs/contributors","subscribers_url":"https://api.github.com/repos/IdanHaim/docs/subscribers","subscription_url":"https://api.github.com/repos/IdanHaim/docs/subscription","commits_url":"https://api.github.com/repos/IdanHaim/docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/IdanHaim/docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/IdanHaim/docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/IdanHaim/docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/IdanHaim/docs/contents/{+path}","compare_url":"https://api.github.com/repos/IdanHaim/docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/IdanHaim/docs/merges","archive_url":"https://api.github.com/repos/IdanHaim/docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/IdanHaim/docs/downloads","issues_url":"https://api.github.com/repos/IdanHaim/docs/issues{/number}","pulls_url":"https://api.github.com/repos/IdanHaim/docs/pulls{/number}","milestones_url":"https://api.github.com/repos/IdanHaim/docs/milestones{/number}","notifications_url":"https://api.github.com/repos/IdanHaim/docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/IdanHaim/docs/labels{/name}","releases_url":"https://api.github.com/repos/IdanHaim/docs/releases{/id}","deployments_url":"https://api.github.com/repos/IdanHaim/docs/deployments","created_at":"2016-08-09T13:43:59Z","updated_at":"2016-08-09T13:44:04Z","pushed_at":"2017-12-26T16:39:42Z","git_url":"git://github.com/IdanHaim/docs.git","ssh_url":"git@github.com:IdanHaim/docs.git","clone_url":"https://github.com/IdanHaim/docs.git","svn_url":"https://github.com/IdanHaim/docs","homepage":"http://ravendb.net","size":52868,"stargazers_count":0,"watchers_count":0,"language":"C#","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":null,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"ravendb:master","ref":"master","sha":"a9c46b789ada0ab9df3eb9e65d6f6b901686b5aa","user":{"login":"ravendb","id":213792,"avatar_url":"https://avatars0.githubusercontent.com/u/213792?v=4","gravatar_id":"","url":"https://api.github.com/users/ravendb","html_url":"https://github.com/ravendb","followers_url":"https://api.github.com/users/ravendb/followers","following_url":"https://api.github.com/users/ravendb/following{/other_user}","gists_url":"https://api.github.com/users/ravendb/gists{/gist_id}","starred_url":"https://api.github.com/users/ravendb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ravendb/subscriptions","organizations_url":"https://api.github.com/users/ravendb/orgs","repos_url":"https://api.github.com/users/ravendb/repos","events_url":"https://api.github.com/users/ravendb/events{/privacy}","received_events_url":"https://api.github.com/users/ravendb/received_events","type":"Organization","site_admin":false},"repo":{"id":961487,"name":"docs","full_name":"ravendb/docs","owner":{"login":"ravendb","id":213792,"avatar_url":"https://avatars0.githubusercontent.com/u/213792?v=4","gravatar_id":"","url":"https://api.github.com/users/ravendb","html_url":"https://github.com/ravendb","followers_url":"https://api.github.com/users/ravendb/followers","following_url":"https://api.github.com/users/ravendb/following{/other_user}","gists_url":"https://api.github.com/users/ravendb/gists{/gist_id}","starred_url":"https://api.github.com/users/ravendb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ravendb/subscriptions","organizations_url":"https://api.github.com/users/ravendb/orgs","repos_url":"https://api.github.com/users/ravendb/repos","events_url":"https://api.github.com/users/ravendb/events{/privacy}","received_events_url":"https://api.github.com/users/ravendb/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ravendb/docs","description":"Documenation book for RavenDB","fork":false,"url":"https://api.github.com/repos/ravendb/docs","forks_url":"https://api.github.com/repos/ravendb/docs/forks","keys_url":"https://api.github.com/repos/ravendb/docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ravendb/docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ravendb/docs/teams","hooks_url":"https://api.github.com/repos/ravendb/docs/hooks","issue_events_url":"https://api.github.com/repos/ravendb/docs/issues/events{/number}","events_url":"https://api.github.com/repos/ravendb/docs/events","assignees_url":"https://api.github.com/repos/ravendb/docs/assignees{/user}","branches_url":"https://api.github.com/repos/ravendb/docs/branches{/branch}","tags_url":"https://api.github.com/repos/ravendb/docs/tags","blobs_url":"https://api.github.com/repos/ravendb/docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ravendb/docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ravendb/docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/ravendb/docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ravendb/docs/statuses/{sha}","languages_url":"https://api.github.com/repos/ravendb/docs/languages","stargazers_url":"https://api.github.com/repos/ravendb/docs/stargazers","contributors_url":"https://api.github.com/repos/ravendb/docs/contributors","subscribers_url":"https://api.github.com/repos/ravendb/docs/subscribers","subscription_url":"https://api.github.com/repos/ravendb/docs/subscription","commits_url":"https://api.github.com/repos/ravendb/docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/ravendb/docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/ravendb/docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/ravendb/docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/ravendb/docs/contents/{+path}","compare_url":"https://api.github.com/repos/ravendb/docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ravendb/docs/merges","archive_url":"https://api.github.com/repos/ravendb/docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ravendb/docs/downloads","issues_url":"https://api.github.com/repos/ravendb/docs/issues{/number}","pulls_url":"https://api.github.com/repos/ravendb/docs/pulls{/number}","milestones_url":"https://api.github.com/repos/ravendb/docs/milestones{/number}","notifications_url":"https://api.github.com/repos/ravendb/docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ravendb/docs/labels{/name}","releases_url":"https://api.github.com/repos/ravendb/docs/releases{/id}","deployments_url":"https://api.github.com/repos/ravendb/docs/deployments","created_at":"2010-10-04T19:12:52Z","updated_at":"2017-09-18T10:01:36Z","pushed_at":"2017-12-26T16:39:52Z","git_url":"git://github.com/ravendb/docs.git","ssh_url":"git@github.com:ravendb/docs.git","clone_url":"https://github.com/ravendb/docs.git","svn_url":"https://github.com/ravendb/docs","homepage":"http://ravendb.net","size":52844,"stargazers_count":88,"watchers_count":88,"language":"C#","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":98,"mirror_url":null,"archived":false,"open_issues_count":5,"license":null,"forks":98,"open_issues":5,"watchers":88,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ravendb/docs/pulls/434"},"html":{"href":"https://github.com/ravendb/docs/pull/434"},"issue":{"href":"https://api.github.com/repos/ravendb/docs/issues/434"},"comments":{"href":"https://api.github.com/repos/ravendb/docs/issues/434/comments"},"review_comments":{"href":"https://api.github.com/repos/ravendb/docs/pulls/434/comments"},"review_comment":{"href":"https://api.github.com/repos/ravendb/docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ravendb/docs/pulls/434/commits"},"statuses":{"href":"https://api.github.com/repos/ravendb/docs/statuses/1730143108d362e3bbe1278e6e4397c28df51237"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"IdanHaim"}}