Skip to main content

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.

  • Altogic automatically provides a default root bucket where you can store your files. You can pretty much do everything with the root bucket that you can do with a normal bucket except you cannot delete or rename it.

Create bucket​

You can create a bucket by calling the createBucket method. It creates a new bucket with the specified name. By default if this method is called within the context of a user session, it also assigns the userId of the session to the bucket metadata. 

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 altogic.storage.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

1namestringYesThe name of the bucket to create (case sensitive). root is a reserved name and cannot be used.
2isPublicbooleanNoThe default privacy setting that will be applied to the files uploaded to this bucket.
3tagsstring arrayNoArray of string values that will be added to the bucket metadata.
info

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.
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 file​

You can delete a file by calling the deleteFile method. It deletes a file identified by the url string. You can directly use this method to delete any file that you know its url. (e.g., no need to specify bucket name/id and file name/id)

let fileUrl =
  "https://c1-na.altogic.com/_storage/6230bfcb1ad5919ab1ad59/6230bfcb1ad5919ab1ad/6230bfcb1ad5919ab1";

// Deletes the file with the specified `fileUrl` string from the root bucket
let { errors } = await altogic.storage.deleteFile(fileUrl);

Parameters​

Here you can find parameters for the deleteFile method.

#

Name

Data type

Required

Description

1fileUrlstringYesThe url of the file that will be deleted from your 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.

Get storage details​

You can get the storage details by calling the getStats method. It returns the overall information about your App 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.

//Gets the storage details of the storage
let result = await altogic.storage.getStats();
Example response
{
  "data": {
    "objectsCount": 5,
    "totalStorageSize": 428037,
    "averageObjectSize": 85607,
    "minObjectSize": 53951,
    "maxObjectSize": 212233,
    "bucketsCount": 2
  },
  "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.

List buckets​

You can list all buckets by calling the listBuckets method and you can define query expressions with bucket fields.

// Returns the first 50 buckets in your app cloud storage
// sorted by bucket creation date in descending order and
// filtered by the specified query expression `isPublic`
// equals to `true`

let result = await altogic.storage.listBuckets("isPublic == true", {
  sort: { field: "createdAt", direction: "desc" },
  limit: 50,
  page: 1,
  returnCountInfo: true,
});
Example response
{
  "data": {
    "info": {
      "count": 2,
      "totalPages": 1,
      "currentPage": 1,
      "pageSize": 50
    },
    "data": [
      {
        "_id": "6233230ba1c88fcb1ad5919a",
        "name": "root",
        "isPublic": true,
        "createdAt": "2022-03-17T12:01:16.118Z",
        "updatedAt": "2022-03-17T12:01:16.118Z"
      },
      {
        "_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
}
info

It returns a list of buckets in your app cloud storage.

  • If query expression is specified, it runs the specified filter query to narrow down returned results, otherwise, returns all buckets contained in your app's cloud storage.

  • If returnCountInfo=true in BucketListOptions, it returns an object which includes the count information and the matching buckets array.

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

Field nameTypeDescription
_idtext (identifier)Unique identifier of the file
nametextName of the bucket
isPublicbooleanDefault privacy setting that will be applied to files of the bucket
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
createdAtdatetime (text)The creation date and time of the bucket
updatedAtdatetime (text)The last modification date and time of bucket metadata

Parameters​

Here you can find parameters for the listBuckets method.

#

Name

Data type

Required

Description

1expressionstringNoThe query expression string that will be used to filter buckets
2optionsBucketListOptionsNoOptions to configure how buckets will be listed, primarily used to set pagination and sorting settings
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.

Search files​

You can search files by calling the searchFiles method. This method performs a global search across all the files contained in all the buckets. 

// Returns the list of files matching the search expression in the cloud storage
// sorted by file upload date in ascending order

let result = await altogic.storage.searchFiles('fileName == "Rooby.png"', {
  {
    limit: 100,
    sort: { field: "uploadedAt", direction: "asc" },
    returnCountInfo: true,
  },
  "true",
);
Example response
{
  "data": {
    "info": {
      "count": 2,
      "totalPages": 1,
      "currentPage": 1,
      "pageSize": 100
    },
    "data": [
      {
        "_id": "623741d545aba7a695579a18",
        "bucketId": "62373bae161326736e4ffde2",
        "fileName": "Rooby-avatar-new.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", "high quality"]
      },
      {
        "_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", "low quality"]
      }
    ]
  },
  "errors": null
}
info

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.

You can use the following file fields in your search expression.

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 searchFiles method.

#

Name

Data type

Required

Description

1expressionstringNoThe query expression string that will be used to filter file objects
2optionsFileListOptionsNoOptions to configure how search result will be listed, primarily used to set pagination and sorting settings
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​

Bucket List Options​

Here you can find the properties for the BucketListOptions

#

Name

Data type

Description

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

Bucket Sort Entry​

Here you can find the properties for the BucketSortEntry

#

Name

Data type

Description

1fieldtextThe name of the bucket field that will be used in sorting the returned objects. It can be name, isPublic, updatedAt, createdAt, userId or tags
2directiontextSort direction. It can be asc or desc