Skip to content

Commit

Permalink
Grammar check.
Browse files Browse the repository at this point in the history
  • Loading branch information
davidbh committed Feb 21, 2018
1 parent 6a2c8e7 commit a15a007
Show file tree
Hide file tree
Showing 6 changed files with 39 additions and 41 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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 /}

Expand All @@ -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:

Expand All @@ -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}

Expand All @@ -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/}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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

Expand All @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand All @@ -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}

Expand All @@ -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/}

Expand All @@ -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/}

Expand Down Expand Up @@ -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/}
Expand All @@ -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/}

Expand Down Expand Up @@ -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 /}
Expand All @@ -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 /}
Expand All @@ -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).

Expand Down
Loading

0 comments on commit a15a007

Please sign in to comment.