Storage
Everything that you store in your app storage must be contained in a bucket. Buckets are the basic containers that hold your application data (i.e., files). You can use buckets to organize your data and control access to your data, but unlike directories and folders, you cannot nest buckets.
Create a bucket
You can create a bucket by calling the createBucket method of your storage. It creates a new
bucket with the specified name. You can specify additional information to store
with each bucket using the tags which is a JSON object (e.g., key-value
pairs).
You can define your storages through Agnost Studio for your app versions.
- Javascript
let storageName = "default";
let bucketName = "profile-images";
// Creates a bucket named `profile-images` with default privacy setting of public,
// meaning that when you add a file to a bucket and if the file did not specify
// public or private setting, then it will be marked as publicly accessible through its URL
let result = await agnost.storage(storageName).createBucket(bucketName);
Example response
{
"data": {
"id": "62373bae161326736e4ffde2",
"name": "profile-images",
"isPublic": true,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T14:35:26.814Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": {}
},
"errors": null
}
Parameters
Here you can find parameters for the createBucket method.
| # | Name | Data type | Required | Description |
|---|---|---|---|---|
| 1 | name | string | Yes | The name of the bucket to create (case sensitive). |
| 2 | isPublic | boolean | No | The default privacy setting that will be applied to the files uploaded to this bucket. |
| 3 | tags | Object | No | JSON object that contains key-value pairs of tags to be added to the bucket metadata. |
| 4 | userId | string or number | No | The unique identifier of the user who created the bucket. |
Buckets can be specified as public or private, which defines how the Public URL of the files will behave.
- Files can be specified as public or private, which defines how the public URL of the file will behave. If a file is marked as private then external apps/parties will not be able to access it through its public URL.
- With isPublic parameter of a bucket, you can specify default privacy setting of the files contained in this bucket, meaning that when you add a file to a bucket and if the file did not specify public/private setting, then the bucket's privacy setting will be applied.
- You can always override the default privacy setting of a bucket at the individual file level.
- If there already exists a bucket with the specified name, it returns an error.
Get storage details
You can get the storage details by calling the getStats method. It returns
summary information about your app version's cloud storage, including the total number
of buckets and files stored, total storage size in bytes and average, min and
max file size in bytes.
- Javascript
let storageName = "default";
// Gets the storage details of the storage
let result = await agnost.storage(storageName).getStats();
Example response
{
"objectsCount": 5,
"totalStorageSize": 428037,
"averageObjectSize": 85607,
"minObjectSize": 53951,
"maxObjectSize": 212233,
"bucketsCount": 2
}
List buckets
You can list all buckets by calling the listBuckets method and you can define
search query.
- Javascript
const storageName = "default";
// Returns the first 50 buckets whose name includes "profile" in your app cloud storage
// sorted by bucket creation date in descending order and also returns pagination info
let result = await agnost.storage(storageName).listBuckets({
search: "profile",
sort: { field: "createdAt", direction: "desc" },
limit: 50,
page: 1,
returnCountInfo: true,
});
Example response
{
"info": {
"count": 2,
"totalPages": 1,
"currentPage": 1,
"pageSize": 50
},
"data": [
{
"id": "bck-o5nnyhs19dgw",
"storageId": "str-o0dlitj2x5id",
"name": "profile-photos",
"isPublic": true,
"createdAt": "2022-03-17T12:01:16.118Z",
"updatedAt": "2022-03-17T12:01:16.118Z",
"tags": {}
},
{
"id": "bck-o0dlitj2x5id",
"storageId": "str-o0dlitj2x5id",
"name": "profile-images",
"isPublic": true,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T14:35:26.814Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": {}
}
]
}
It returns a list of buckets in your app cloud storage matching the search query.
- If returnCountInfo=true in BucketListOptions, it returns an object which includes the count information and the matching buckets array.
Parameters
Here you can find parameters for the listBuckets method.
| # | Name | Data type | Required | Description |
|---|---|---|---|---|
| 1 | options | BucketListOptions | No | Options to configure how buckets will be listed, primarily used to set pagination and sorting settings |
List files
You can list files by calling the listFiles method. This method performs a
global search across all the files contained in all the buckets.
- Javascript
const storageName = "default";
// Returns the list of files that includes "avatar" in their name
// sorted by file upload date in ascending order
let result = await agnost.storage(storageName).listFiles({
search: "avatar",
limit: 100,
sort: { field: "uploadedAt", direction: "asc" },
returnCountInfo: true,
});
Example response
{
"info": {
"count": 2,
"totalPages": 1,
"currentPage": 1,
"pageSize": 100
},
"data": [
{
"id": "fl-32fw342234ed",
"bucketId": "bck-o5nnyhs19dgw",
"storageId": "str-o0dlitj2x5id",
"path": "Rooby-avatar-new.png",
"size": 212233,
"mimeType": "image/png",
"isPublic": true,
"uploadedAt": "2022-03-20T15:01:41.993Z",
"updatedAt": "2022-03-20T15:01:41.993Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": {"size": "large", "quality": "high quality"}
},
{
"id": "fl-3fd34rdgg6345",
"bucketId": "bck-o5nnyhs19dgw",
"storageId": "str-o0dlitj2x5id",
"path": "Rooby-avatar-2.png",
"size": 53951,
"mimeType": "image/png",
"isPublic": true,
"uploadedAt": "2022-03-20T15:01:00.916Z",
"updatedAt": "2022-03-20T15:01:00.916Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": {"size": "small", "quality": "low quality"}
}
]
}
It returns the list of files matching the search query.
This method performs a global search across all the files contained in all the buckets.
If returnCountInfo=true in FileListOptions, it returns an object which includes count information and array of matching files.
Parameters
Here you can find parameters for the listFiles method.
| # | Name | Data type | Required | Description |
|---|---|---|---|---|
| 1 | options | FileListOptions | No | Options to configure how search result will be listed, primarily used to set pagination and sorting settings |
If the client library key is set to enforce session, an active user session is required (e.g., user needs to be logged in) to call this method.
Options
File List Options
Here you can find the properties for the FileListOptions
| # | Name | Data type | Description |
|---|---|---|---|
| 1 | limit | number | A positive integer that specifies the max number of buckets to return per page. |
| 2 | page | number | A positive integer that specifies the page number to paginate bucket results. Page numbers start from 1. |
| 3 | returnCountInfo | boolean | Flag to specify whether to return the count and pagination information such as total number of buckets, page number and page size. |
| 4 | sort | FileSortEntry | Specifies the field name and sort direction for sorting returned buckets. |
| 5 | search | string | The search string parameter. Agnost searches the bucket names that includes the search string. |
Bucket List Options
Here you can find the properties for the BucketListOptions
| # | Name | Data type | Description |
|---|---|---|---|
| 1 | limit | number | A positive integer that specifies the max number of buckets to return per page. |
| 2 | page | number | A positive integer that specifies the page number to paginate bucket results. Page numbers start from 1. |
| 3 | returnCountInfo | boolean | Flag to specify whether to return the count and pagination information such as total number of buckets, page number and page size. |
| 4 | sort | BucketSortEntry | Specifies the field name and sort direction for sorting returned buckets. |
| 5 | search | string | The search string parameter. Agnost searches the bucket names that includes the search string. |
Bucket Sort Entry
Here you can find the properties for the BucketSortEntry
| # | Name | Data type | Description |
|---|---|---|---|
| 1 | field | text | The name of the bucket field that will be used in sorting the returned objects. It can be name, isPublic, updatedAt, createdAt, userId or tags |
| 2 | direction | text | Sort direction. It can be asc or desc |
File Sort Entry
Here you can find the properties for the FileSortEntry
| # | Name | Data type | Description |
|---|---|---|---|
| 1 | field | text | The name of the file field that will be used in sorting the returned objects. It can be bucketId, name, size, contentType, isPublic, uploadedAt, updatedAt or userId |
| 2 | direction | text | Sort direction. It can be asc or desc |