|
| 1 | +Blobs are binary large objects that can used to store any type of unstructured/binary data and is designed for large content. Blobs support streaming and feature better performance for content larger than about 20KB. Blobs are built off the native JavaScript `Blob` type, and HarperDB extends the native `Blob` type for integrated storage with the database. To use blobs, you would generally want to declare a field as a `Blob` type in your schema: |
| 2 | +```graphql |
| 3 | +type MyTable { |
| 4 | + id: Any! @primaryKey |
| 5 | + data: Blob |
| 6 | +} |
| 7 | +``` |
| 8 | + |
| 9 | +You can then create a blob which writes the binary data to disk, and can then be included (as a reference) in a record. For example, you can create a record with a blob like: |
| 10 | + |
| 11 | +```javascript |
| 12 | +let blob = await createBlob(largeBuffer); |
| 13 | +await MyTable.put({ id: 'my-record', data: blob }); |
| 14 | +``` |
| 15 | +The `data` attribute in this example is a blob reference, and can be used like any other attribute in the record, but it is stored separately, and the data must be accessed asynchronously. You can retrieve the blob data with the standard `Blob` methods: |
| 16 | + |
| 17 | +```javascript |
| 18 | +let buffer = await blob.bytes(); |
| 19 | +``` |
| 20 | + |
| 21 | +If you are creating a resource method, you can return a `Response` object with a blob as the body: |
| 22 | + |
| 23 | +```javascript |
| 24 | +export class MyEndpoint extends MyTable { |
| 25 | + async get() { |
| 26 | + return { |
| 27 | + status: 200, |
| 28 | + headers: {}, |
| 29 | + body: this.data, // this.data is a blob |
| 30 | + }); |
| 31 | + } |
| 32 | +} |
| 33 | +``` |
| 34 | +One of the important characteristics of blobs is they natively support asynchronous streaming of data. This is important for both creation and retrieval of large data. When we create a blob with `createBlob`, the returned blob will create the storage entry, but the data will be streamed to storage. This means that you can create a blob from a buffer or from a stream. You can also create a record that references a blob before the blob is fully written to storage. For example, you can create a blob from a stream: |
| 35 | + |
| 36 | +```javascript |
| 37 | +let blob = await createBlob(stream); |
| 38 | +// at this point the blob exists, but the data is still being written to storage |
| 39 | +await MyTable.put({ id: 'my-record', data: blob }); |
| 40 | +// we now have written a record that references the blob |
| 41 | +let record = await MyTable.get('my-record'); |
| 42 | +// we now have a record that gives us access to the blob. We can asynchronously access the blob's data or stream the data, and it will be available as blob the stream is written to the blob. |
| 43 | +let stream = record.data.stream(); |
| 44 | +``` |
| 45 | +This can be powerful functionality for large media content, where content can be streamed into storage as it streamed out in real-time to users as it is received. |
| 46 | +Alternately, we can also wait for the blob to be fully written to storage before creating a record that references the blob: |
| 47 | + |
| 48 | +```javascript |
| 49 | +let blob = await createBlob(stream); |
| 50 | +// at this point the blob exists, but the data is was not been written to storage |
| 51 | +await blob.save(MyTable); |
| 52 | +// we now know the blob is fully written to storage |
| 53 | +await MyTable.put({ id: 'my-record', data: blob }); |
| 54 | +``` |
| 55 | + |
| 56 | +Note that this means that blobs are _not_ atomic or [ACID](https://en.wikipedia.org/wiki/ACID) compliant; streaming functionality achieves the opposite behavior of ACID/atomic writes that would prevent access to data as it is being written. |
| 57 | + |
| 58 | +### Error Handling |
| 59 | +Because blobs can be streamed and referenced prior to their completion, there is a chance that an error or interruption could occur while streaming data to the blob (after the record is committed). We can create an error handler for the blob to handle the case of an interrupted blob: |
| 60 | + |
| 61 | +```javascript |
| 62 | +export class MyEndpoint extends MyTable { |
| 63 | + let blob = this.data; |
| 64 | + blob.on('error', () => { |
| 65 | + // if this was a caching table, we may want to invalidate or delete this record: |
| 66 | + this.invalidate(); |
| 67 | + }); |
| 68 | + async get() { |
| 69 | + return { |
| 70 | + status: 200, |
| 71 | + headers: {}, |
| 72 | + body: blob |
| 73 | + }); |
| 74 | + } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +See the [configuration](../../deployments/configuration.md) documentation for more information on configuring where blob are stored. |
0 commit comments