Skip to main content

Buckets

Buckets are primarily used to manage your files and its contents (e.g., files, documents, images).

Upload file

You can upload a file to an existing bucket by calling the upload method. If there already exists a file with the same name in destination bucket, it ensures the uploaded file name to be unique in its bucket.

//Uploads a file to the profiles-images bucket
let bucketName = "profiles-images";
const fileToUpload = event.target.files[0];
const result = await altogic.storage
.bucket(bucketName)
.upload(fileToUpload.name, fileToUpload);

//If you would like to have a progress indicator during file upload
//you can also provide a callback function with `onProgress` property
const result = await altogic.storage
.bucket(bucketName)
.upload(fileToUpload.name, fileToUpload, {
onProgress: (uploaded, total, percent) =>
console.log(`progress: ${uploaded}/${total} ${percent}`),
});
Example response
{
"data": {
"_id": "62373fbb0b72592107523d7d",
"bucketId": "62373bae161326736e4ffde2",
"fileName": "ice.png",
"size": 53951,
"encoding": "7bit",
"mimeType": "image/png",
"publicPath": "https://c1-na.altogic.com/_storage/623323/0ba1c889a/62373bae1/6132d",
"isPublic": true,
"uploadedAt": "2022-03-20T14:52:43.213Z",
"updatedAt": "2022-03-20T14:52:43.213Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": []
},
"errors": null
}

Parameters

Here you can find parameters for the upload method.

#

Name

Data type

Required

Description

1fileNamestringYesThe name of the file e.g., rooby-avatar.jpg
2fileBodyanyYesThe body of the file that will be stored in the bucket
3optionsFileUploadOptionsNoContent type of the file, privacy setting of the file, tags of the file and whether to create the bucket if not exists. contentType is ignored, if fileBody is Blob, File or FormData, otherwise contentType option needs to be specified.
If not specified, contentType will default to text/plain;charset=UTF-8.
If isPublic is not specified, defaults to the bucket's privacy setting. If createBucket is set to true (defaults to false), then creates a new bucket if the bucket does not exist.
info

If onProgress callback function is defined in FileUploadOptions, it periodically calls this function to inform about upload progress.

Once you upload a file to bucket, it is stored in the staging area for a few seconds for internal processing. That means that you might not be able to access the file for a few seconds after it is uploaded.

note

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.

List files in bucket

You can get the list of files stored in the bucket by calling the listFiles method.

let bucket = "profile-images";

// Returns the list of files in bucket profile-images with
// count info and sorted by their size in ascending order
const result = await altogic.storage.bucket(bucket).listFiles({
returnCountInfo: true,
sort: { field: "size", direction: "asc" },
});

/*
You can also apply filters and paginate over the files.
Below call returns the first 100 of files which are marked
as public and sorted by their size in ascending order
*/
const result = await altogic.storage
.bucket(bucket)
.listFiles("isPublic == true", {
returnCountInfo: true,
limit: 100,
page: 1,
sort: { field: "size", direction: "asc" },
});
Example response
{
"data": {
"info": {
"count": 5,
"totalPages": 1,
"currentPage": 1,
"pageSize": 100
},
"data": [
{
"_id": "623741d545aba7a695579a18",
"bucketId": "62373bae161326736e4ffde2",
"fileName": "Booby.png",
"size": 212233,
"encoding": "7bit",
"mimeType": "image/png",
"publicPath": "https://c1-na.altogic.com/_storage/6233230ba1c88fcb1ad5919a/62373bae161326736e4ffde2/623741d545aba7a695579a18",
"isPublic": true,
"uploadedAt": "2022-03-20T15:01:41.993Z",
"updatedAt": "2022-03-20T15:01:41.993Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": ["large"]
},
{
"_id": "623741ac161326736e4ffde4",
"bucketId": "62373bae161326736e4ffde2",
"fileName": "Rooby.png",
"size": 53951,
"encoding": "7bit",
"mimeType": "image/png",
"publicPath": "https://c1-na.altogic.com/_storage/6233230ba1c88fcb1ad5919a/62373bae161326736e4ffde2/623741ac161326736e4ffde4",
"isPublic": true,
"uploadedAt": "2022-03-20T15:01:00.916Z",
"updatedAt": "2022-03-20T15:01:00.916Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": ["small"]
},
{
"_id": "623741a8158fe88838fff085",
"bucketId": "62373bae161326736e4ffde2",
"fileName": "Fluufy.png",
"size": 53951,
"encoding": "7bit",
"mimeType": "image/png",
"publicPath": "https://c1-na.altogic.com/_storage/6233230ba1c88fcb1ad5919a/62373bae161326736e4ffde2/623741a8158fe88838fff085",
"isPublic": true,
"uploadedAt": "2022-03-20T15:00:56.614Z",
"updatedAt": "2022-03-20T15:00:56.614Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": ["small"]
},
{
"_id": "623741a545aba7a695579a17",
"bucketId": "62373bae161326736e4ffde2",
"fileName": "Teddy.png",
"size": 53951,
"encoding": "7bit",
"mimeType": "image/png",
"publicPath": "https://c1-na.altogic.com/_storage/6233230ba1c88fcb1ad5919a/62373bae161326736e4ffde2/623741a545aba7a695579a17",
"isPublic": true,
"uploadedAt": "2022-03-20T15:00:53.747Z",
"updatedAt": "2022-03-20T15:00:53.747Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": ["small"]
},
{
"_id": "6237419e161326736e4ffde3",
"bucketId": "62373bae161326736e4ffde2",
"fileName": "Winnie.png",
"size": 53951,
"encoding": "7bit",
"mimeType": "image/png",
"publicPath": "https://c1-na.altogic.com/_storage/6233230ba1c88fcb1ad5919a/62373bae161326736e4ffde2/6237419e161326736e4ffde3",
"isPublic": true,
"uploadedAt": "2022-03-20T15:00:46.275Z",
"updatedAt": "2022-03-20T15:00:46.275Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": ["small"]
}
]
},
"errors": null
}
info
  • If query expression is specified, it runs the specified filter query to narrow down returned results, otherwise, returns all files contained in the bucket. You can use the file fields in table below in your query expressions.

  • If returnCountInfo=true in FileListOptions, it returns an object which includes count information and a list of files.

You can use the following file fields in your query expressions.

Field nameTypeDescription
_idtext (identifier)Unique identifier of the file
bucketIdtext (identifier)Identifier of the bucket
fileNametextName of the file
isPublicbooleanWhether file is publicy accessible or not
sizeintegerSize of the file in bytes
encodingtextThe encoding type of the file such as 7bit, utf8
mimeTypetextThe mime-type of the file such as image/gif, text/html
publicPathtextThe public path (URL) of the file
userIdtext (identifier)The unique identifier of the user who created the bucket. The userId information is populated only when the bucket is created within the context of a user session.
tagsstring arrayList of tags added to the bucket metadata
uploadedAtdatetime (text)The upload date and time of the file
updatedAtdatetime (text)The last modification date and time of file metadata

Parameters

Here you can find parameters for the listFiles method.

#

Name

Data type

Required

Description

1expressionstringNoThe query expression string that will be used to filter file objects
2optionsFileListOptionsNoPagination and sorting options
note

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.

Get bucket info

You can get information about the bucket by calling the getInfo method.

let bucketName = "profile-images";

// Returns the information about the bucket `profile-images`.
const result = await altogic.storage.bucket(bucketName).getInfo(true);
Example response
{
"data": {
"_id": "62373bae161326736e4ffde2",
"name": "profile-images",
"isPublic": true,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T14:35:26.814Z",
"tags": [],
"userId": "62c14524cf074016b1045366",
"stats": {
"objectsCount": 5,
"totalStorageSize": 428037,
"averageObjectSize": 85607,
"minObjectSize": 53951,
"maxObjectSize": 212233
}
},
"errors": null
}
info
  • It returns basic bucket metadata informaton.
  • If detailed=true, it provides additional information about the total number of files contained, their overall total size in bytes, average, min and max file size in bytes etc.

Parameters

Here you can find parameters for the getInfo method.

#

Name

Data type

Required

Description

1detailedbooleanNoSpecifies whether to get detailed bucket statistics or not, default false
note

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.

Check whether bucket exists

You can check whether the bucket exists or not by calling the exists method. If the bucket exists, it returns true, otherwise false.

let bucketName = "profile-images";

// Checks the `profile-images` bucket whether it exists or not
const result = await altogic.storage.bucket(bucketName).exists();
Example response
{
"data": true,
"errors": null
}
note

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.

Make bucket public

You can make the bucket public by calling the makePublic method. It sets the privacy of the bucket to true.

tip

You may also choose to make the contents of the bucket publicly accessible by specifying includeFiles=true.

  • This will automatically set isPublic=true for every file in the bucket.
let bucketName = "profile-images";

// Makes the `profile-images` bucket and contents public.
const result = await altogic.storage.bucket(bucketName).makePublic(true);
Example response
{
"data": {
"_id": "62373bae161326736e4ffde2",
"name": "profile-images",
"isPublic": true,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T16:13:20.206Z",
"tags": [],
"userId": "62c14524cf074016b1045366"
},
"errors": null
}

Parameters

Here you can find parameters for the makePublic method.

#

Name

Data type

Required

Description

1includeFilesbooleanNoSpecifies whether to make each file in the bucket public.
note

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.

Make bucket private

You can make the bucket private by calling the makePrivate method. It sets the privacy of the bucket to false.

tip

You may also choose to make the contents of the bucket private by specifying includeFiles=true.

  • This will automatically set isPublic=false for every file in the bucket.
let bucketName = "profile-images";

// Makes the `profile-images` bucket and contents private.
const result = await altogic.storage.bucket(bucketName).makePrivate(true);
Example response
{
"data": {
"_id": "62373bae161326736e4ffde2",
"name": "profile-images",
"isPublic": false,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T16:14:29.332Z",
"tags": [],
"userId": "62c14524cf074016b1045366"
},
"errors": null
}

Parameters

Here you can find parameters for the makePrivate method.

#

Name

Data type

Required

Description

1includeFilesbooleanNoSpecifies whether to make each file in the bucket private.
note

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.

Delete files

You can delete file(s) from the bucket by calling the deleteFiles method. It deletes single or multiple files identified either by their names or ids.

let bucketName = "profile-images";

// Deletes the `profile-image-1.jpg` and `profile-image-2.jpg`
// files from the `profile-images` bucket.

const { errors } = await altogic.storage
.bucket(bucketName)
.deleteFiles(["profile-image-1.jpg", "profile-image-2.jpg"]);

Parameters

Here you can find parameters for the deleteFiles method.

#

Name

Data type

Required

Description

1fileNamesOrIdsstring[]YesList of name or id of the files to be deleted.
note

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.

Rename Bucket

You can rename the bucket name by calling the rename method.

let newName = "device-images";
let oldName = "asset-images";

// Renames the `asset-images` bucket to `device-images`.
const result = await altogic.storage.bucket(oldName).rename(newName);
Example response
{
"data": {
"_id": "623745881182562412d85ce0",
"name": "device-images",
"isPublic": true,
"createdAt": "2022-03-20T15:17:28.439Z",
"updatedAt": "2022-03-20T16:18:33.953Z",
"tags": [],
"userId": "62c14524cf074016b1045366"
},
"errors": null
}

Parameters

Here you can find parameters for the rename method.

#

Name

Data type

Required

Description

1newNamestringYesThe new name of the bucket. root is a reserved name and cannot be used.
note

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.

Delete Bucket

You can delete the bucket by calling the delete method. It deletes the bucket and all objects (e.g., files) inside the bucket.

let bucketName = "profile-images";

// Deletes the `profile-images` bucket and all its contents.
const { errors } = await altogic.storage.bucket(bucketName).delete();
note

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.

Empty Bucket

You can empty the bucket by calling the empty method. It removes all objects (e.g., files) inside the bucket.

info
  • This method does not delete the bucket itself.
  • If you also want to delete the bucket, including all its contained objects, you can use delete method.
let bucketName = "profile-images";

// Empties the `profile-images` bucket.
const { errors } = await altogic.storage.bucket(bucketName).empty();
note

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.

Add tags to bucket

You can add your own tags to each bucket. This metadata can be used in expressions to filter buckets or store data specific to your application.

let bucketName = "profile-images";

const result = await altogic.storage.bucket(bucketName).addTags(["picture", "user", "profile"]);
Example response
{
"data": {
"_id": "62373bae161326736e4ffde2",
"name": "profile-images",
"isPublic": true,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T16:13:20.206Z",
"tags": ["picture", "user", "profile"],
"userId": "62c14524cf074016b1045366"
},
"errors": null
}

Parameters

Here you can find parameters for the addTags method.

#

Name

Data type

Required

Description

1tagsstring or string[]YesA single tag or an array of tags to add to bucket's metadata.
note

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.

Remove tags from bucket

You can also remove tags (e.g., your custom metadata associated with your app storage buckets) from your buckets.

let bucketName = "profile-images";

const result = await altogic.storage.bucket(bucketName).removeTags("profile");
Example response
{
"data": {
"_id": "62373bae161326736e4ffde2",
"name": "profile-images",
"isPublic": true,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T16:13:20.206Z",
"tags": ["picture", "user"],
"userId": "62c14524cf074016b1045366"
},
"errors": null
}

Parameters

Here you can find parameters for the removeTags method.

#

Name

Data type

Required

Description

1tagsstring or string[]YesA single tag or an array of tags to remove from bucket's metadata.
note

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.

Update bucket info

You can update the overall bucket information (name, isPublic and tags) in a single method call, instead of calling each individual update method separately.

let bucketName = "profile-images";

const result = await altogic.storage.bucket(bucketName).updateInfo("pictures", false,
["user", "profile", "pictures"], true);
Example response
{
"data": {
"_id": "62373bae161326736e4ffde2",
"name": "pictures",
"isPublic": false,
"createdAt": "2022-03-20T14:35:26.814Z",
"updatedAt": "2022-03-20T16:13:20.206Z",
"tags": ["user", "profile", "pictures"],
"userId": "62c14524cf074016b1045366"
},
"errors": null
}

Parameters

Here you can find parameters for the updateInfo method.

#

Name

Data type

Required

Description

1newNamestringYesThe new name of the bucket. root is a reserved name and cannot be used.
2isPublicbooleanYesThe default privacy setting that will be applied to the files uploaded to this bucket.
3tagsstring or string[]YesArray of string values that will be set as the bucket metadata.
4includeFilesbooleanNoSpecifies whether to make each file in the bucket to have the same privacy setting of the bucket..
note

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 Upload Options

You can define the options for the file upload by using the FileUploadOptions. It defines the available options that can be set during file upload.

#

Name

Data type

Description

1contentTypestringThe Content-Type header value. This value needs to be specified if using a fileBody that is neither Blob nor File nor FormData, otherwise will default to text/plain;charset=UTF-8.
2isPublicbooleanSpecifies whether file is publicy accessible or not. Defaults to the bucket's privacy setting if not specified.
3createBucketbooleanSpecifies whether to create the bucket while uploading the file. If a bucket with the provided name does not exists and if createBucket is marked as true then creates a new bucket. Defaults to false.
4onProgresscallback functionCallback function to call during file upload to get upload progress.
Parameters
1. uploaded number Total bytes uploaded
2. total number Total size of file in bytes
3. percent number Percent uploaded (an integer between 0-100), basicly uploaded/total rounded to the nearest integer
5tagsstring arrayArray of string values that will be added to the file metadata.
info

For the moment, onProgress callback function can only be used in clients where XMLHttpRequest object is available (e.g., browsers).

File List Options

You can define the options for the file list by using the FileListOptions. It defines the structure how to get the files of a bucket.

#

Name

Data type

Description

1limitnumberA positive integer that specifies the max number of files to return per page.
2pagenumberA positive integer that specifies the page number to paginate file results. Page numbers start from 1.
3returnCountInfobooleanFlag to specify whether to return the count and pagination information such as total number of files, page number and page size.
4sortFileSortEntrySpecifies the field name and sort direction for sorting returned files.

File Sort Entry

Here you can find the properties for the FileSortEntry

#

Name

Data type

1fieldThe name of the file field that will be used in sorting the returned objects
It can be either isPublic, updatedAt, bucketId, fileName, size, encoding, mimeType, publicPath, userId, tags or uploadedAt
2directionSort direction
It can be asc or desc