Skip to content

Commit 5fee8a7

Browse files
rstamrstam
committed
CSHARP-1395: GridFS documentation.
1 parent bb8afb9 commit 5fee8a7

File tree

8 files changed

+485
-2
lines changed

8 files changed

+485
-2
lines changed

‎Docs/reference/content/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,4 @@ If you are coming from the 2.0.x series of the driver, consult the [upgrading]({
2222

2323
## Reference
2424

25-
If you are looking for more detailed documentation, see the [Reference]({{< relref "reference\index.md" >}}) guide.
25+
If you are looking for more detailed documentation, see the [Reference]({{< relref "reference\index.md" >}}) guide.

‎Docs/reference/content/reference/gridfs/deletingandrenamingfiles.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
+++
2+
date = "2015-09-41T00:00:00Z"
3+
draft = false
4+
title = "Deleting and Renaming Files"
5+
[menu.main]
6+
parent = "GridFS"
7+
identifier = "GridFS Deleting and Renaming Files"
8+
weight = 50
9+
pre = "<i class='fa'></i>"
10+
+++
11+
12+
## Deleting and Renaming Files
13+
14+
These methods allow you to delete or rename GridFS files.
15+
16+
### Deleting a single file
17+
18+
The DeleteAsync method is used to delete a single file identified by its Id.
19+
20+
```
21+
IGridFSBucket bucket;
22+
ObjectId id;
23+
24+
await bucket.DeleteAsync(id);
25+
```
26+
27+
### Dropping an entire GridFS bucket
28+
29+
If you want to drop an entire GridFS bucket at once use the DropAsync method.
30+
31+
```
32+
IGridFSBucket bucket;
33+
34+
await bucket.DropAsync();
35+
```
36+
37+
The "fs.files" collection will be dropped first, followed by the "fs.chunks" collection. This is the fastest way to delete all files stored in a GridFS bucket at once.
38+
39+
### Renaming a single file
40+
41+
The RenameAsync method is used to rename a single file identified by its Id.
42+
43+
```
44+
IGridFSBucket bucket;
45+
ObjectId id;
46+
string newFilename;
47+
48+
await bucket.RenameAsync(id, newFilename);
49+
```
50+
51+
### Renaming all revisions of a file
52+
53+
If you want to rename all revisions of a file you first use FindAsync to find their ids and then call RenameAsync in a loop to rename them one at a time.
54+
55+
```
56+
IGridFSBucket bucket;
57+
ObjectId id;
58+
string oldFilename;
59+
string newFilename;
60+
61+
var filter = Builders<GridFSFileInfo>.Filter.EQ(x => x.Filename, oldFilename);
62+
var filesCursor = await bucket.FindAsync(filter);
63+
var files = await filesCursor.ToListAsync();
64+
65+
foreach (var file in files)
66+
{
67+
await bucket.RenameAsync(file.Id, newFilename);
68+
}
69+
```

‎Docs/reference/content/reference/gridfs/downloadingfiles.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
+++
2+
date = "2015-09-41T00:00:00Z"
3+
draft = false
4+
title = "Downloading Files"
5+
[menu.main]
6+
parent = "GridFS"
7+
identifier = "GridFS Downloading Files"
8+
weight = 30
9+
pre = "<i class='fa'></i>"
10+
+++
11+
12+
## Downloading Files
13+
14+
There are several ways to download a file from GridFS. The two main approaches are:
15+
16+
1. The driver downloads a file as a byte array or by writing the contents to a Stream provided by the application
17+
2. The driver supplies a Stream object that the application can read the contents from
18+
19+
### Downloading as a byte array
20+
21+
This is the easiest way to download a file from GridFS, assuming that the file is small enough for the entire contents to be held in memory at once.
22+
23+
```
24+
IGridFSBucket bucket;
25+
ObjectId id;
26+
27+
var bytes = await bucket.DownloadAsBytesAsync(id);
28+
```
29+
30+
### Downloading to a Stream
31+
32+
If you don't want to hold the entire contents of the downloaded file in memory at once, you can have the driver write the contents of the file to a Stream provided by the application.
33+
34+
```
35+
IGridFSBucket bucket;
36+
ObjectId id;
37+
Stream destination;
38+
39+
await bucket.DownloadToStreamAsync(id, destination);
40+
```
41+
42+
The driver will download the contents of the GridFS file and write them to the destination Stream. The driver begins writing the contents at the current position of the Stream, and does **not** close the Stream when it is done. The Stream is owned by the application and it is up to the application to close the Stream when it is ready to do so.
43+
44+
### Downloading from a Stream
45+
46+
In some cases it the application might prefer to read the contents of the GridFS file from a Stream.
47+
48+
```
49+
IGridFSBucket bucket;
50+
ObjectId id;
51+
52+
using (var stream = await bucket.OpenDownloadStreamAsync(id))
53+
{
54+
// read from stream until end of file is reached
55+
await stream.CloseAsync();
56+
}
57+
```
58+
59+
The Stream object returned by OpenDownloadStreamAsync is actually a GridFSDownloadStream (a subclass of Stream), which has the following additional members in addition to those found in Stream:
60+
61+
```
62+
public abstract class GridFSDownloadStream : Stream
63+
{
64+
public abstract GridFSFileInfo FileInfo { get; }
65+
public abstract Task CloseAsync(CancellationToken cancellationToken = default(CancellationToken));
66+
};
67+
```
68+
69+
The FileInfo property contains information about the GridFS file being dowloaded. See the FindAsync method for details about the GridFSFileInfo class.
70+
71+
Calling CloseAsync is optional, but recommended. Since Stream is IDisposable and it is used inside a using statement, it would be closed automatically when Dispose is called. However, in async programming we want to avoid blocking and calling CloseAsync first allows the Stream to be closed with an async call. If you call CloseAsync first then Dispose will no longer block.
72+
73+
By default the driver assumes that you want to read the entire contents of the file from beginning to end, and returns a Stream implementation that does not support seeking, which allows for a more efficient implementation.
74+
75+
If you do want to use Seek with the returned Stream, you can use the options parameter to indicate that.
76+
77+
```
78+
IGridFSBucket bucket;
79+
ObjectId id;
80+
81+
var options = new GridFSDownloadOptions
82+
{
83+
Seekable = true
84+
};
85+
86+
using (var stream = await bucket.OpenDownloadStreamAsync(id, options))
87+
{
88+
// this time the Stream returned supports seeking
89+
await stream.CloseAsync();
90+
}
91+
```
92+
93+
### Downloading by filename
94+
95+
All the previous examples used an Id to specify which GridFS file to download. You can also use a filename to specify which GridFS file to download, but in this case you might need to indicate which "revision" of the file you want to download if there are multiple GridFS files with the same filename.
96+
97+
Revisions are identified using an integer, as follows:
98+
99+
- 0 = the original version uploaded
100+
- 1 = the first revision of the file
101+
- 2 = the second revision of the file
102+
- ...
103+
- -2 the second newest revision of the file
104+
- -1 the newest revision of the file
105+
106+
The default value for the revision is -1 (i.e. the newest revision).
107+
108+
The following examples all download the newest revision:
109+
110+
```
111+
IGridFSBucket bucket;
112+
string filename;
113+
114+
var bytes = await bucket.DownloadAsBytesByNameAsync(filename);
115+
116+
// or
117+
118+
Stream destination;
119+
await bucket.DownloadToStreamByNameAsync(filename, destination);
120+
121+
// or
122+
123+
using (var stream = await bucket.OpenDownloadStreamByNameAsync(filename))
124+
{
125+
// read from stream until end of file is reached
126+
await stream.CloseAsync();
127+
}
128+
```
129+
130+
If you want to download a different revision, you specify the desired revision using the options parameter.
131+
132+
```
133+
IGridFSBucket bucket;
134+
string filename;
135+
136+
var options = new GridFSDownloadByNameOptions
137+
{
138+
Revision = 0
139+
};
140+
141+
var bytes = await bucket.DownloadAsBytesByNameAsync(filename, options);
142+
143+
// or
144+
145+
Stream destination;
146+
await bucket.DownloadToStreamByNameAsync(filename, destination, options);
147+
148+
// or
149+
150+
using (var stream = await bucket.OpenDownloadStreamByNameAsync(filename, options))
151+
{
152+
// read from stream until end of file is reached
153+
await stream.CloseAsync();
154+
}
155+
```
156+

‎Docs/reference/content/reference/gridfs/findingfiles.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
+++
2+
date = "2015-09-41T00:00:00Z"
3+
draft = false
4+
title = "Finding Files"
5+
[menu.main]
6+
parent = "GridFS"
7+
identifier = "GridFS Finding Files"
8+
weight = 40
9+
pre = "<i class='fa'></i>"
10+
+++
11+
12+
## Finding Files
13+
14+
Each file stored in GridFS has a unique Id assigned to it, and that is the primary way of accessing the stored files.
15+
16+
### FindAsync method
17+
18+
If you don't know the Id, you can use FindAsync to find matching files using a filter. The filter must be of type FilterDefinition&lt;GridFSFileInfo&gt;.
19+
20+
For example, to find the newest revision of the file named "securityvideo" uploaded in January 2015 we could use FindAsync like this:
21+
22+
```
23+
IGridFSBucket bucket;
24+
var filter = Builders<GridFSFileInfo>.Filter.And(
25+
Builders<GridFSFileInfo>.Filter.EQ(x => x.Filename, "securityvideo"),
26+
Builders<GridFSFileInfo>.Filter.GTE(x => x.UploadDateTime, new DateTime(2015, 1, 1, 0, 0, 0, DateTimeKind.Utc)),
27+
Builders<GridFSFileInfo>.Filter.LT(x => x.UploadDateTime, new DateTime(2015, 2, 1, 0, 0, 0, DateTimeKind.Utc)));
28+
var sort = Builders<GridFSFileInfo>.Sort.Descending(x => x.UploadDateTime);
29+
var options = new GridFSFindOptions
30+
{
31+
Limit = 1,
32+
Sort = sort
33+
};
34+
35+
using (var cursor = await bucket.FindAsync(filter, options))
36+
{
37+
var fileInfo = (await cursor.ToListAsync()).FirstOrDefault();
38+
// fileInfo either has the matching file information or is null
39+
}
40+
```
41+
42+
### GridFSFileInfo class
43+
44+
The GridFSFileInfo is a strongly typed class that represents the information about a GridFS file stored in the "fs.files" collection.
45+
46+
It is defined as:
47+
48+
```
49+
public class GridFSFileInfo
50+
{
51+
public BsonDocument BackingDocument { get; }
52+
public int ChunkSizeBytes { get; }
53+
public string Filename { get; }
54+
public ObjectId Id { get; }
55+
public long Length { get; }
56+
public string MD5 { get; }
57+
public BsonDocument Metadata { get; }
58+
public DateTime UploadDateTime { get; }
59+
60+
// the following are deprecated but kept for backward compatibility
61+
public IEnumerable<string> Aliases { get; }
62+
public string ContentType { get; }
63+
public BsonValue IdAsBsonValue { get; }
64+
}
65+
```
66+
67+
This class is a strongly typed wrapper around a backing BsonDocument. It makes it easier to extract the information available in a files collection documents.
68+
69+
In older drivers it was possible to store arbitrary information at the root level of a files collection document. If you need to access that information you can use the BackingDocument property to get access to the complete backing document. When uploading new GridFS files you should store any additional information you want to associate with the uploaded file inside the Metadata document.

‎Docs/reference/content/reference/gridfs/gettingstarted.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
+++
2+
date = "2015-09-41T00:00:00Z"
3+
draft = false
4+
title = "Getting Started"
5+
[menu.main]
6+
parent = "GridFS"
7+
identifier = "GridFS Getting Started"
8+
weight = 10
9+
pre = "<i class='fa'></i>"
10+
+++
11+
12+
## Getting Started
13+
14+
GridFS files are stored in the database using two collections, normally called "fs.files" and "fs.chunks". Each file uploaded to GridFS has one document in the "fs.files" containing information about the file and as many chunks as necessary in the "fs.chunks" collection to store the contents of the file.
15+
16+
A GridFS "bucket" is the combination of an "fs.files" and "fs.chunks" collection which together represent a bucket where GridFS files can be stored.
17+
18+
### GridFSBucket
19+
20+
A GridFSBucket object is the root object representing a GridFS bucket. You should always use a GridFSBucket object to interact with GridFS instead of directly referencing the underlying collections.
21+
22+
You create a GridFSBucket instance by calling its constructor:
23+
24+
```
25+
IMongoDatabase database;
26+
27+
var bucket = new GridFSBucket(database);
28+
```
29+
30+
You can also provide options when instantiating the GridFSBucket object:
31+
32+
```
33+
IMongoDatabase database;
34+
35+
var bucket = new GridFSBucket(database, new GridFSOptions
36+
{
37+
BucketName = "videos",
38+
ChunkSizeBytes = 1048576, // 1MB
39+
WriteConcern = WriteConcern.Majority,
40+
ReadPreference = ReadPeference.Secondary
41+
});
42+
```
43+
44+
The BucketName value is the root part of the files and chunks collection names, so in this example the two collections would be named "videos.files" and "videos.chunks" instead of "fs.files" and "fs.chunks".
45+
46+
The ChunkSizeBytes value defines the size of each chunk, and in this example we are overriding the default value of 261120 (255MB).
47+
48+
The WriteConcern is used when uploading files to GridFS, and the ReadPreference is used when downloading files from GridFS.

‎Docs/reference/content/reference/gridfs/index.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
+++
2+
date = "2015-09-11T00:00:00Z"
3+
draft = false
4+
title = "GridFS"
5+
[menu.main]
6+
parent = "Reference"
7+
identifier = "GridFS"
8+
weight = 40
9+
pre = "<i class='fa'></i>"
10+
+++
11+
12+
## GridFS
13+
14+
GridFS is a way of storing binary information that is larger than the maximum document size (currently 16MB). When you upload a file to GridFS the file is broken into chunks and the individual chunks are uploaded. When you download a file from GridFS the original content is reassembled from the chunks.
15+
16+
- [Getting Started]({{< relref "reference\gridfs\gettingstarted.md" >}})
17+
- [Uploading files]({{< relref "reference\gridfs\uploadingfiles.md" >}})
18+
- [Downloading files]({{< relref "reference\gridfs\downloadingfiles.md" >}})
19+
- [Finding files]({{< relref "reference\gridfs\findingfiles.md" >}})
20+
- [Deleting and renaming files]({{< relref "reference\gridfs\deletingandrenamingfiles.md" >}})

0 commit comments

Comments
 (0)