diff --git a/Documentation/4.0/Raven.Documentation.Pages/indexes/map-reduce-indexes.markdown b/Documentation/4.0/Raven.Documentation.Pages/indexes/map-reduce-indexes.markdown index c68c79730a..6ca0ba35c9 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/indexes/map-reduce-indexes.markdown +++ b/Documentation/4.0/Raven.Documentation.Pages/indexes/map-reduce-indexes.markdown @@ -4,7 +4,7 @@ Map-Reduce indexes allow you to perform complex aggregations of data. The first Upon completion of the first phase, reduction is applied to the map results and the final outcome is produced. The idea behind map-reduce indexing is that aggregation queries using such indexes are very cheap. The aggregation is performed only once and the results are stored inside the index. -Once new data come into the database or existing documents are modified, the map-reduce index will keep the aggregation results up-to-date. The aggregations are never done during +Once new data comes into the database or existing documents are modified, the map-reduce index will keep the aggregation results up-to-date. The aggregations are never done during querying to avoid expensive calculations that could result in severe performance degradation. When you make the query, RavenDB immediately returns the matching results directly from the index. For a more in-depth look at how map reduce works, you can read this post: [RavenDB 4.0 Unsung Heroes: Map/reduce](https://ayende.com/blog/179938/ravendb-4-0-unsung-heroes-map-reduce). @@ -31,11 +31,11 @@ where Category == 'Seafood' {CODE-TAB-BLOCK/} {CODE-TABS/} -The above query will return one result for _Seafood_, with the appropriate number of products from that category. +The above query will return one result for _Seafood_ with the appropriate number of products from that category. ### Example II - Average -In this example, we will count average product price for each category. The index definition: +In this example, we will count an average product price for each category. The index definition: {CODE map_reduce_1_0@Indexes\MapReduceIndexes.cs /} @@ -52,7 +52,7 @@ where Category == 'Seafood' ### Example III - Calculations -This example illustrates how we can put some calculations inside an index using on one of the indexes available in sample database (`Product/Sales`). +This example illustrates how we can put some calculations inside an index using on one of the indexes available in the sample database (`Product/Sales`). We want to know how many times each product was ordered and how much we earned for it. In order to extract that information, we need to define the following index: @@ -73,14 +73,14 @@ from 'Product/Sales' {PANEL:Reduce Results as Artificial Documents} In addition to storing the aggregation results in the index, the map-reduce indexes can also output reduce results as documents to a specified collection. -In order to create such documents, called _artificial_, you need to define the target collection using `OutputReduceToCollection` property in the index definition. +In order to create such documents, called _artificial_, you need to define the target collection using the `OutputReduceToCollection` property in the index definition. {CODE map_reduce_3_0@Indexes\MapReduceIndexes.cs /} -Writing map-reduce outputs into documents allows to define additional indexes on top of them that gives you the option to create recursive map-reduce operations. -This ways you can do daily/monthly/yearly summaries very cheaply and easy. +Writing map-reduce outputs into documents allows you to define additional indexes on top of them that give you the option to create recursive map-reduce operations. +This way, you can do daily/monthly/yearly summaries very cheaply and easy. -In addition to that, you can also apply all the usual operations on documents (e.g. data subscriptions or ETL). +In addition, you can also apply the usual operations on documents (e.g. data subscriptions or ETL). {INFO: Saving documents} @@ -93,10 +93,10 @@ Artificial documents are stored immediately after the indexing transaction compl It's forbidden to output reduce results to the collection that: - the current index is already working on (e.g. index on `DailyInvoices` collections outputs to `DailyInvoices`), -- the current index is loading document from it (e.g. index has `LoadDocument(id, "Invoices")` outputs to `Invoices`), -- it is processed by another map-reduce index that outputs result to a collection that the current index is working on (e.g. one index on `Invoices` collection outputs to `DailyInvoices`, another index on `DailyInvoices` outputs to `Invoices`) +- the current index is loading a document from it (e.g. index has `LoadDocument(id, "Invoices")` outputs to `Invoices`), +- it is processed by another map-reduce index that outputs results to a collection that the current index is working on (e.g. one index on `Invoices` collection outputs to `DailyInvoices`, another index on `DailyInvoices` outputs to `Invoices`) -because that would result in the infinite indexing loop (the index puts an artificial document what triggers the indexing and so on). You will get the detailed error on attempt to create such invalid construction. +Since that would result in the infinite indexing loop (the index puts an artificial document what triggers the indexing and so on), you will get the detailed error on attempt to create such invalid construction. {WARNING/} diff --git a/Documentation/4.0/Raven.Documentation.Pages/migration/server/bundles.markdown b/Documentation/4.0/Raven.Documentation.Pages/migration/server/bundles.markdown index 90fd39939b..b9e0087f9e 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/migration/server/bundles.markdown +++ b/Documentation/4.0/Raven.Documentation.Pages/migration/server/bundles.markdown @@ -10,7 +10,7 @@ Authorization is based on [client X.509 certificates](../../server/security/auth {PANEL:Cascade Delete} -The attachments are always tied to their documents. The deletion of a documents results in removing all its attachments as well (in the same transaction). +The attachments are always tied to their documents. The deletion of a document results in removing all its attachments as well (in the same transaction). Deletion of referenced / child documents needs to be handled by your application. You just simply need to call `session.Delete()` for related documents when deleting the main one. diff --git a/Documentation/4.0/Raven.Documentation.Pages/server/configuration/storage-configuration.markdown b/Documentation/4.0/Raven.Documentation.Pages/server/configuration/storage-configuration.markdown index e8c4d6e2df..fc949c8c16 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/server/configuration/storage-configuration.markdown +++ b/Documentation/4.0/Raven.Documentation.Pages/server/configuration/storage-configuration.markdown @@ -4,7 +4,7 @@ The following configuration options allow you configure [the storage engine](../ {PANEL:Storage.TempPath} -You can use this setting to specify a different path to temporary files. By default it is empty, which means that temporary files will be created at same location as data file under `Temp` directory. +You can use this setting to specify a different path to temporary files. By default it is empty, which means that temporary files will be created at same location as data file under the `Temp` directory. - **Type**: `string` - **Default**: `null` diff --git a/Documentation/4.0/Raven.Documentation.Pages/server/storage-engine.markdown b/Documentation/4.0/Raven.Documentation.Pages/server/storage-engine.markdown index e34bcc604c..f6dd499ffd 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/server/storage-engine.markdown +++ b/Documentation/4.0/Raven.Documentation.Pages/server/storage-engine.markdown @@ -1,18 +1,17 @@ #Storage Engine - Voron -RavenDB uses in-house managed storage engine called Voron to persist the data (documents, indexes and configuration). It the high performance storage engine -that was designed and optimized to the needs of RavenDB. It uses the following structures underneath that allow to organize the data on persistent storage efficiently: +RavenDB uses an in-house managed storage engine called Voron to persist your data (documents, indexes and configuration). It's a high performance storage engine designed and optimized to the needs of RavenDB. It uses the following structures underneath that allow it to organize the data on persistent storage efficiently: - B+Tree - variable size key and value -- Fixed Sized B+Tree - `Int64` key and fixed size value (defined at creation time). It allows to take advantage of various optimizations -- Raw Data Section – it allows to store raw data (e.g. documents content) and gives an identifier that allows access the data in O(1) time +- Fixed Sized B+Tree - `Int64` key and fixed size value (defined at creation time). It allows you to take advantage of various optimizations +- Raw Data Section – it allows you to store raw data (e.g. documents content) and gives an identifier that allows access to the data in O(1) time - Table – combination of Raw Data Sections with any number of indexes that under the hood are regular or Fixed Size B+Trees ## Transaction Support Voron is fully transactional storage engine. It uses Write Ahead Journal (WAJ) to guarantee atomicity and durability features. All modifications made within a transaction are written to a journal file (unbuffered I/O, write-through) before they are applied to the main data file (and synced to disk). The WAJ application is done in -the background. If the process stopped working and left some modifications not applied to the data file then the database will recover its state on load by replying +the background. If the process stopped working and left some modifications not applied to the data file, then the database will recover its state on load by replying the transactions persisted in the journal files. As the journals are flushed and synced to disk before returning on each transaction commit it guarantees they will survive the event of a process or system crash. @@ -23,11 +22,11 @@ Snapshot isolation for concurrent transactions is provided by Page Translation T ## Single Write Model -Voron supports only single write process (but there can be multiple read processes). Having only a single write transaction simplifies handling of writes. +Voron supports only single write processes (but there can be multiple read processes). Having only a single write transaction simplifies the handling of writes. In order to provide high performance, RavenDB implements transaction merging on top of that what gives us a tremendous performance boost in high load scenarios. -In addition to that Voron has the notion of async transaction commit (with a list of requirements that must happen to be exactly fit in the transaction merging portion in RavenDB), -and the actual transaction lock handoff / early lock released is handled at a higher layer, with a lot more information about the system. +In addition to that, Voron has the notion of async transaction commit (with a list of requirements that must happen to be exactly fit in the transaction merging portion in RavenDB), +and the actual transaction lock handoff / early lock released is handled at a higher layer with a lot more information about the system. ## Memory Mapped File @@ -36,7 +35,7 @@ Voron is based on memory mapped files. {INFO: Running on 32 bits} Since RavenDB 4.0, Voron has no limits when running in 32 bits mode. The issue of running out of address space when mapping files into memory -has been addressed by providing a dedicated pager (component responsible for mapping) for 32 bits environments. +has been addressed by providing a dedicated pager (component responsible for mapping) for a 32 bits environments. Instead of mapping an entire file, it maps just the pages that are required and only for the duration of the transaction. diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/getting-started.markdown b/Documentation/4.0/Raven.Documentation.Pages/start/getting-started.markdown index 53c478725a..8df92b6059 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/start/getting-started.markdown +++ b/Documentation/4.0/Raven.Documentation.Pages/start/getting-started.markdown @@ -5,7 +5,7 @@ Welcome to this introductory article that will guide you through all the parts o This article consists of two parts: - The [Server](../start/getting-started#server) part will focus on installation, setup & configuration of the RavenDB server -- The [Client](../start/getting-started#client) part will describe general principles behind our client libraries +- The [Client](../start/getting-started#client) part will describe the general principles behind our client libraries {PANEL: Server} @@ -23,7 +23,7 @@ RavenDB is cross-platform with support for the following operating systems: ### Prerequisites -RavenDB is written in .NET Core, because of that it requires the same set of prerequisites as .NET Core. +RavenDB is written in .NET Core so it requires the same set of prerequisites as .NET Core. {NOTE: Windows} @@ -33,7 +33,7 @@ Please install [Visual C++ 2015 Redistributable Package](https://support.microso {NOTE: Linux} -We highly recommend **updating** your **Linux OS** prior to launching the RavenDB server. Please also check if .NET Core requires any other prerequisites in the [Prerequisites for .NET Core on Linux](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites) article written by Microsoft. +We highly recommend **updating** your **Linux OS** prior to launching the RavenDB server. Also check if .NET Core requires any other prerequisites in the [Prerequisites for .NET Core on Linux](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites) article written by Microsoft. {NOTE/} @@ -47,11 +47,11 @@ We highly recommend **updating** your **MacOS** and checking the [Prerequisites ### Installation & Setup -After extraction of the server package you can start the [Setup Wizard](../start/installation/setup-wizard) by running the `run.ps1` (or `run.sh`) script or by [disabling the 'Setup Wizard' and configuring the server manually](../start/installation/manual). +After extraction of the server package, you can start the [Setup Wizard](../start/installation/setup-wizard) by running the `run.ps1` (or `run.sh`) script or by [disabling the 'Setup Wizard' and configuring the server manually](../start/installation/manual). {NOTE: Running in a Docker container} -If you are interested in hosting the server in a Docker container. Please read our [dedicated article](../start/installation/running-in-docker-container). +If you are interested in hosting the server in a Docker container, please read our [dedicated article](../start/installation/running-in-docker-container). {NOTE/} @@ -117,7 +117,7 @@ To let a developer start coding an application quickly, RavenDB will run with th As long as the database is used inside the local machine and no outside connections are allowed, you can ignore security concerns and you require no authentication. Once you set RavenDB to listen to connections outside your local machine, -your database will immediately block this now vulnerable configuration, and require the administrator to properly setup the security and +your database will immediately block this now vulnerable configuration and require the administrator to properly setup the security and access control to prevent unauthorized access to your data or to explicitly allow the unsecured configuration. {WARNING/} @@ -143,11 +143,11 @@ After your server is up and running, to write an application you need to acquire ### DocumentStore -In order to start you need to create an instance of the `DocumentStore` - the main entry point for your application which is responsible for establishing and managing connections between a RavenDB server (or cluster) and your application. +In order to start, you need to create an instance of the `DocumentStore` - the main entry point for your application which is responsible for establishing and managing connections between a RavenDB server (or cluster) and your application. {INFO:Examples} -Before proceeding to the examples we would like to point out that most of the articles are using the `Northwind` database. You can read more about it and how to deploy it [here](../studio/database/tasks/create-sample-data). +Before proceeding to the examples, we would like to point out that most of the articles are using the `Northwind` database. You can read more about it and how to deploy it [here](../studio/database/tasks/create-sample-data). {INFO/} @@ -179,7 +179,7 @@ The `Session` is used to manipulate the data. It implements the `Unit of Work` p ### Example I - Storing -RavenDB is a Document Database, which means that all stored objects are called `documents`. Each document contains a **unique ID** that identifies it, **data** and adjacent **metadata**, both stored in JSON format. The metadata contains information describing the document, e.g. the last modification date (`@last-modified` property) or the [collection](../client-api/faq/what-is-a-collection) (`@collection` property) assignment. +RavenDB is a Document Database. All stored objects are called `documents`. Each document contains a **unique ID** that identifies it, **data** and adjacent **metadata**, both stored in JSON format. The metadata contains information describing the document, e.g. the last modification date (`@last-modified` property) or the [collection](../client-api/faq/what-is-a-collection) (`@collection` property) assignment. {CODE-TABS} {CODE-TAB:csharp:C# client_2@Start/GettingStarted.cs /} @@ -190,9 +190,9 @@ RavenDB is a Document Database, which means that all stored objects are called ` ### Example II - Loading -The `Session` was designed to help the user write efficient code easily. For example, when a document is being loaded (`.Load`) from the server, there is an option to retrieve additional documents in the same request (using `.Include`), reducing the number of expensive calls to minimum. +The `Session` was designed to help the user write efficient code easily. For example, when a document is being loaded (`.Load`) from the server, there is an option to retrieve additional documents in the same request (using `.Include`), keeping the number of expensive calls to minimum. -Besides that, the session implements the `Unit of Work` pattern, meaning that all **changes** to loaded entities are **automatically tracked**. The `SaveChanges` call will synchronize (with the server) **only the documents that have changed within the session**. Worth noting at this point is that **all of those changes are send in one request (saving network calls)** and **processed in one transaction** (you can read why RavenDB is an **ACID database** [here](../client-api/faq/transaction-support)). +Besides that, the session implements the `Unit of Work` pattern, meaning that all **changes** to loaded entities are **automatically tracked**. The `SaveChanges` call will synchronize (with the server) **only the documents that have changed within the session**. **All of those changes are sent in one request (saving network calls)** and **processed in one transaction** (you can read why RavenDB is an **ACID database** [here](../client-api/faq/transaction-support)). {CODE-TABS} {CODE-TAB:csharp:C# client_3@Start/GettingStarted.cs /} @@ -205,7 +205,7 @@ Besides that, the session implements the `Unit of Work` pattern, meaning that al To satisfy queries, indexes are used. From the querying perspective, an index defines which document fields can be used to find a document. The whole indexing process is done asynchronously, which gives very quick querying response times, even when large amounts of data have been changed. However, an implication of this approach is that the index might be [stale](../indexes/stale-indexes). -When no index is specified in the query (like in the query below), then RavenDB will use its **intelligent auto-indexes** feature that will either use an already existing index or create a new one if no match is found. The other options is to write the index yourself and deploy it to the server. Those indexes are called [Static Indexes](../indexes/creating-and-deploying#static-indexes). +When no index is specified in the query (like in the query below), RavenDB will use its **intelligent auto-indexes** feature that will either use an already existing index or create a new one if no match is found. The other option is to write the index yourself and deploy it to the server. Those indexes are called [Static Indexes](../indexes/creating-and-deploying#static-indexes). Behind the scenes, queries are translated to the Raven Query Language (RQL) syntax. Read more about RQL [here](../indexes/querying/what-is-rql). diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-wizard.markdown b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-wizard.markdown index 1bd8cb6eab..d5cc80a397 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-wizard.markdown +++ b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-wizard.markdown @@ -25,12 +25,11 @@ During the wizard, RavenDB will give you a free subdomain. It lets you configure The free subdomain is given to you only for the purpose of proving ownership to Let's Encrypt. If you wish to use your own domain, you are welcome to acquire your own certificate and use that instead. - {WARNING: Security consideration and ownership of certificates and domains} -The automatic setup is designed to be as convenient and as easy as possible, it takes care of all the nitpicks of setting up DNS records, generating certificates and doing their renewals. Because of those requirements, the ownership of the certificates and DNS records needs to stay within the Hibernating Rhinos company. This gives us the ability to generate valid certificates and modify DNS settings for your registered domains and should be a consideration to keep in mind while reviewing the security of your system. Hibernating Rhinos **will never** exploit these abilities and will never perform any modifications to the certificates and DNS records unless explicitly requested by the client. +The automatic setup is designed to be as convenient and as easy as possible. It takes care of all the nitpicks of setting up DNS records, generating certificates, and doing their renewals. Because of those requirements, the ownership of the certificates and DNS records needs to stay within the Hibernating Rhinos company. This gives us the ability to generate valid certificates and modify DNS settings for your registered domains and should be a consideration to keep in mind while reviewing the security of your system. Hibernating Rhinos **will never** exploit these abilities and will never perform any modifications to the certificates and DNS records unless explicitly requested by the client. -The purpose of this feature is to make it easy for users to get setup and running with a minimum of fuzz, but we **recommend** that for actual production deployments and for the highest level of security and control, you'll use **your own certificates and domains**, avoiding the need to rely on third party for such a critical part of your security. +The purpose of this feature is to make it easy for users to get set up and running with a minimum of fuzz. We **recommend** that for actual production deployments and for the highest level of security and control, you'll use **your own certificates and domains**, avoiding the need to rely on third party for such a critical part of your security. {WARNING/} @@ -144,7 +143,7 @@ Now, let's bring node B up. First, copy the configuration Zip file to node B and download/copy a fresh RavenDB server folder. In **Windows**, start RavenDB using the `run.ps1` script. In **Linux**, use the `start.sh` script. -This time, we will choose to continue the cluster setup. +This time we will choose to continue the cluster setup. ![Figure 9. Continue Setup](images/setup/10.png) @@ -165,7 +164,7 @@ You have successfully finished setting up a secure cluster of RavenDB servers us In RavenDB, users can provide their own server certificate. The certificate can be issued by a trusted SSL vendor or it can be a self-signed certificate. In the latter case, it's the user's responsibility to have the self-signed CA registered in the OS stores on all the relevant machines. -RavenDB will accept PFX server certificates which contain the private key, are not expired and have the following fields: +RavenDB will accept PFX server certificates which contain the private key, are not expired, and have the following fields: - KeyUsage: DigitalSignature, KeyEncipherment - ExtendedKeyUsage: Client Authentication, Server Authentication @@ -190,7 +189,7 @@ When you provide a wildcard certificate, node tags are assigned automatically in If you wish to use different domain names or build a cluster with more than 26 nodes you can either do a manual setup or use the wizard and provide a certificate with as many domains as you need under the "Subject Alternative Names" (SAN) property. {NOTE/} {WARNING: Important} -If you bring your own certificate you must also take care of the DNS records. If you choose to bind to 127.0.0.1, and provide a certificate with CN=my.domain, then the DNS record of my.domain must point to 127.0.0.1. +If you bring your own certificate, you must also take care of the DNS records. If you choose to bind to 127.0.0.1, and provide a certificate with CN=my.domain, then the DNS record of my.domain must point to 127.0.0.1. If you are running behind a firewall, the DNS records must point to the **external** IP address. {WARNING/} @@ -243,7 +242,7 @@ Then the following congifuration should be applied: ![Figure 2a. Configure Docker Node](images/setup/w2a.png) -When finished you will receive a Zip file containing all of the cluster configuration files and certificates. In case you are setting up a cluster, you will use this Zip file to setup the other nodes. +When finished, you will receive a Zip file containing all of the cluster configuration files and certificates. In case you are setting up a cluster, you will use this Zip file to setup the other nodes. ![Figure 3. Configuration Completed](images/setup/w3.png)