Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 135 lines (80 sloc) 4.469 kB
9dcb15e added gridstore
andris9 authored
1 GridStore
2 ======
3
a0105bb @christkv Attempting reformating
authored
4 GridFS is a scalable MongoDB *filesystem* for storing and retrieving large files. The default limit for a MongoDB record is 16MB, so to store data that is larger than this limit, GridFS can be used. GridFS shards the data into smaller chunks automatically. See [MongoDB documentation](http://www.mongodb.org/display/DOCS/GridFS+Specification) for details.
9dcb15e added gridstore
andris9 authored
5
6 GridStore is a single file inside GridFS that can be managed by the script.
7
8 ## Open GridStore
9
10 Opening a GridStore (a single file in GridFS) is a bit similar to opening a database. At first you need to create a GridStore object and then `open` it.
11
12 var gs = new mongodb.GridStore(db, filename, mode[, options])
13
14 Where
15
16 * `db` is the database object
17 * `filename` is the name of the file in GridFS that needs to be accessed/created
f123855 @Nican Added description of what each of the 3 file modes does, and how to u…
Nican authored
18 * `mode` indicated the operaion, can be one of:
19 * "r" (Read): Looks for the file information in fs.files collection, or creates a new id for this object.
20 * "w" (Write): Erases all chunks if the file already exist.
21 * "w+" (Append): Finds the last chunk, and keeps writing after it.
9dcb15e added gridstore
andris9 authored
22 * `options` can be used to specify some metadata for the file, for example `content_type`, `metadata` and `chunk_size`
23
24 Example:
25
26 var gs = new mongodb.GridStore(db, "test.png", "w", {
27 "content_type": "image/png",
28 "metadata":{
29 "author": "Daniel"
30 },
31 "chunk_size": 1024*4
32 });
33
f123855 @Nican Added description of what each of the 3 file modes does, and how to u…
Nican authored
34 When GridStore object is created, it needs to be opened.
9dcb15e added gridstore
andris9 authored
35
36 gs.open(callback);
37
38 `callback` gets two parameters - and error object (if error occured) and the GridStore object.
39
943e451 added gridstore
andris9 authored
40 Opened GridStore object has a set of useful properties
41
44193f1 updated readme
andris9 authored
42 * `gs.length` - length of the file in bytes
943e451 added gridstore
andris9 authored
43 * `gs.contentType` - the content type for the file
44 * `gs.uploadDate` - when the file was uploaded
45 * `gs.metadata` - metadata that was saved with the file
46 * `gs.chunkSize` - chunk size
47
7810cce added gridstore
andris9 authored
48 Example
49
50 gs.open(function(err, gs){
51 console.log("this file was uploaded at "+gs.uploadDate);
52 });
53
9dcb15e added gridstore
andris9 authored
54 ## Writing to GridStore
55
56 Writing can be done with `write`
57
58 gs.write(data, callback)
59
60 where `data` is a `Buffer` or a string, callback gets two parameters - an error object (if error occured) and result value which indicates if the write was successful or not.
61
7810cce added gridstore
andris9 authored
62 While the GridStore is not closed, every write is appended to the opened GridStore.
9dcb15e added gridstore
andris9 authored
63
f123855 @Nican Added description of what each of the 3 file modes does, and how to u…
Nican authored
64 ## Writing a file to GridStore
65
66 This functions opens the gridstore, streams the contents of the file into gridstore, and closes the gridstore.
67
68 gs.writeFile( file, callback )
69
70 where
71
72 * `file` is a file descriptior, or a string file path
73 * `callback` is a function with two parameters - error object (if error occured) and the GridStore object.
74
75
9dcb15e added gridstore
andris9 authored
76 ## Reading from GridStore
77
78 Reading from GridStore can be done with `read`
79
975df8e @epeli Remove false offset docs from GridStore.
epeli authored
80 gs.read([size], callback)
9dcb15e added gridstore
andris9 authored
81
82 where
83
84 * `size` is the length of the data to be read
85 * `callback` is a callback function with two parameters - error object (if an error occured) and data (binary string)
947572d updated gridfs
andris9 authored
86
f123855 @Nican Added description of what each of the 3 file modes does, and how to u…
Nican authored
87 ## Streaming from GridStore
88
89 You can stream data as it comes from the database using `stream`
90
91 gs.stream([autoclose=false])
92
93 where
94
95 * `autoclose` If true current GridStore will be closed when EOF and 'close' event will be fired
96
97 The function returns [read stream](http://nodejs.org/docs/v0.4.12/api/streams.html#readable_Stream) based on this GridStore file. It supports the events 'read', 'error', 'close' and 'end'.
98
947572d updated gridfs
andris9 authored
99 ## Delete a GridStore
100
101 GridStore files can be unlinked with `unlink`
102
103 mongodb.GridStore.unlink(db, name, callback)
104
105 Where
106
107 * `db` is the databse object
108 * `name` is either the name of a GridStore object or an array of GridStore object names
109 * `callback` is the callback function
110
9dcb15e added gridstore
andris9 authored
111 ## Closing the GridStore
112
44193f1 updated readme
andris9 authored
113 GridStore needs to be closed after usage. This can be done with `close`
9dcb15e added gridstore
andris9 authored
114
115 gs.close(callback)
116
117 ## Check the existance of a GridStore file
118
119 Checking if a file exists in GridFS can be done with `exist`
120
947572d updated gridfs
andris9 authored
121 mongodb.GridStore.exist(db, filename, callback)
9dcb15e added gridstore
andris9 authored
122
123 Where
124
125 * `db` is the database object
4571af8 @christkv Added some more tests, small fixes, cleanup and docs
authored
126 * `filename` is the name of the file to be checked or a regular expression
9dcb15e added gridstore
andris9 authored
127 * `callback` is a callback function with two parameters - an error object (if an error occured) and a boolean value indicating if the file exists or not
128
129 ## Seeking in a GridStore
130
131 Seeking can be done with `seek`
132
133 gs.seek(position);
134
135 This function moves the internal pointer to the specified position.
Something went wrong with that request. Please try again.