1# JavaScript API
2
3## DBWrapper
4
5### Constructor
6
7    # Creates a new database wrapper object
8    RDB()
9
10### Open
11
12    # Open a new or existing RocksDB database.
13    #
14    # db_name         (string)   - Location of the database (inside the
15    #                              `/tmp` directory).
16    # column_families (string[]) - Names of additional column families
17    #                              beyond the default. If there are no other
18    #                              column families, this argument can be
19    #                              left off.
20    #
21    # Returns true if the database was opened successfully, or false otherwise
22    db_obj.(db_name, column_families = [])
23
24### Get
25
26    # Get the value of a given key.
27    #
28    # key           (string) - Which key to get the value of.
29    # column_family (string) - Which column family to check for the key.
30    #                          This argument can be left off for the default
31    #                          column family
32    #
33    # Returns the value (string) that is associated with the given key if
34    # one exists, or null otherwise.
35    db_obj.get(key, column_family = { default })
36
37### Put
38
39    # Associate a value with a key.
40    #
41    # key           (string) - Which key to associate the value with.
42    # value         (string) - The value to associate with the key.
43    # column_family (string) - Which column family to put the key-value pair
44    #                          in. This argument can be left off for the
45    #                          default column family.
46    #
47    # Returns true if the key-value pair was successfully stored in the
48    # database, or false otherwise.
49    db_obj.put(key, value, column_family = { default })
50
51### Delete
52
53    # Delete a value associated with a given key.
54    #
55    # key           (string) - Which key to delete the value of..
56    # column_family (string) - Which column family to check for the key.
57    #                          This argument can be left off for the default
58    #                          column family
59    #
60    # Returns true if an error occurred while trying to delete the key in
61    # the database, or false otherwise. Note that this is NOT the same as
62    # whether a value was deleted; in the case of a specified key not having
63    # a value, this will still return true. Use the `get` method prior to
64    # this method to check if a value existed before the call to `delete`.
65    db_obj.delete(key, column_family = { default })
66
67### Dump
68
69    # Print out all the key-value pairs in a given column family of the
70    # database.
71    #
72    # column_family (string) - Which column family to dump the pairs from.
73    #                          This argument can be left off for the default
74    #                          column family.
75    #
76    # Returns true if the keys were successfully read from the database, or
77    # false otherwise.
78    db_obj.dump(column_family = { default })
79
80### WriteBatch
81
82    # Execute an atomic batch of writes (i.e. puts and deletes) to the
83    # database.
84    #
85    # cf_batches (BatchObject[]; see below) - Put and Delete writes grouped
86    #                                         by column family to execute
87    #                                         atomically.
88    #
89    # Returns true if the argument array was well-formed and was
90    # successfully written to the database, or false otherwise.
91    db_obj.writeBatch(cf_batches)
92
93### CreateColumnFamily
94
95    # Create a new column family for the database.
96    #
97    # column_family_name (string) - Name of the new column family.
98    #
99    # Returns true if the new column family was successfully created, or
100    # false otherwise.
101    db_obj.createColumnFamily(column_family_name)
102
103### CompactRange
104
105    # Compact the underlying storage for a given range.
106    #
107    # In addition to the endpoints of the range, the method is overloaded to
108    # accept a non-default column family, a set of options, or both.
109    #
110    # begin (string)         - First key in the range to compact.
111    # end   (string)         - Last key in the range to compact.
112    # options (object)       - Contains a subset of the following key-value
113    #                          pairs:
114    #                            * 'target_level'   => int
115    #                            * 'target_path_id' => int
116    # column_family (string) - Which column family to compact the range in.
117    db_obj.compactRange(begin, end)
118    db_obj.compactRange(begin, end, options)
119    db_obj.compactRange(begin, end, column_family)
120    db_obj.compactRange(begin, end, options, column_family)
121
122
123
124### Close
125
126    # Close an a database and free the memory associated with it.
127    #
128    # Return null.
129    # db_obj.close()
130
131
132## BatchObject
133
134### Structure
135
136A BatchObject must have at least one of the following key-value pairs:
137
138* 'put' => Array of ['string1', 'string1'] pairs, each of which signifies that
139the key 'string1' should be associated with the value 'string2'
140* 'delete' => Array of strings, each of which is a key whose value should be
141deleted.
142
143The following key-value pair is optional:
144
145* 'column_family' => The name (string) of the column family to apply the
146changes to.
147
148### Examples
149
150    # Writes the key-value pairs 'firstname' => 'Saghm' and
151    # 'lastname' => 'Rossi' atomically to the database.
152    db_obj.writeBatch([
153        {
154            put: [ ['firstname', 'Saghm'], ['lastname', 'Rossi'] ]
155        }
156    ]);
157
158
159    # Deletes the values associated with 'firstname' and 'lastname' in
160    # the default column family and adds the key 'number_of_people' with
161    # with the value '2'. Additionally, adds the key-value pair
162    # 'name' => 'Saghm Rossi' to the column family 'user1' and the pair
163    # 'name' => 'Matt Blaze' to the column family 'user2'. All writes
164    # are done atomically.
165    db_obj.writeBatch([
166        {
167            put: [ ['number_of_people', '2'] ],
168            delete: ['firstname', 'lastname']
169        },
170        {
171            put: [ ['name', 'Saghm Rossi'] ],
172            column_family: 'user1'
173        },
174        {
175            put: [ ['name', Matt Blaze'] ],
176            column_family: 'user2'
177        }
178    ]);
179