From d4d2c94373a17acbf459d13207150068a4c64d84 Mon Sep 17 00:00:00 2001 From: fenos Date: Mon, 9 Sep 2024 13:14:26 +0200 Subject: [PATCH 1/4] docs: storage metadata,info,exists --- .../NavigationMenu.constants.ts | 8 +-- .../guides/storage/management/exists.mdx | 19 +++++++ .../guides/storage/management/metadata.mdx | 52 +++++++++++++++++++ .../storage/uploads/resumable-uploads.mdx | 16 ++++++ .../storage/uploads/standard-uploads.mdx | 12 +++++ 5 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 apps/docs/content/guides/storage/management/exists.mdx create mode 100644 apps/docs/content/guides/storage/management/metadata.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index 82f44a46ef823..acd9d970dbfbf 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -1460,11 +1460,13 @@ export const storage: NavMenuConstant = { ], }, { - name: 'Management', + name: 'Objects', url: undefined, items: [ - { name: 'Copy / Move Objects', url: '/guides/storage/management/copy-move-objects' }, - { name: 'Delete Objects', url: '/guides/storage/management/delete-objects' }, + { name: 'Metadata', url: '/guides/storage/management/metadata' }, + { name: 'Exists', url: '/guides/storage/management/exists' }, + { name: 'Copy / Move ', url: '/guides/storage/management/copy-move-objects' }, + { name: 'Delete', url: '/guides/storage/management/delete-objects' }, ], }, { diff --git a/apps/docs/content/guides/storage/management/exists.mdx b/apps/docs/content/guides/storage/management/exists.mdx new file mode 100644 index 0000000000000..441cc34880f9b --- /dev/null +++ b/apps/docs/content/guides/storage/management/exists.mdx @@ -0,0 +1,19 @@ +--- +id: 'storage-management' +title: 'Object Exists' +description: 'Learn how to check if an object exists' +subtitle: 'Learn how to check if an object exists' +sidebar_label: 'Object Exists' +--- + +To determine if an object exists in a bucket, use the `exists` method. +RLS is applied to this method, meaning that the user must have the `read` permission on the object to check if it exists. + +```javascript +const { data, error } = await supabase.storage.from('bucket_name').exists('path/your/object.png') + +console.log(data) // true or false +``` + +## Consistency Guarantees +Storage provides [strong read-after-write consistency](https://aws.amazon.com/s3/consistency/) for object existence checks. When the object is uploaded or deleted, the `exists` method will return the correct result immediately. \ No newline at end of file diff --git a/apps/docs/content/guides/storage/management/metadata.mdx b/apps/docs/content/guides/storage/management/metadata.mdx new file mode 100644 index 0000000000000..d35ce9f2e76ec --- /dev/null +++ b/apps/docs/content/guides/storage/management/metadata.mdx @@ -0,0 +1,52 @@ +--- +id: 'storage-management' +title: 'Object Metadata' +description: 'Learn how to store and retrieve object metadata' +subtitle: 'Learn how to get object metadata' +sidebar_label: 'Object Metadata' +--- + +## Object Metadata +Each object in a bucket can have metadata associated with it. Metadata is a set of key-value pairs that describe the object. +You can use metadata to store information such as the object's content type, author, or any other custom data. + + +Each upload method in the Storage API accepts a `metadata` option that allows you to add custom metadata to the object. +Please refer to the followings guides for more information on how to upload objects with metadata.: + +- [Standard Uploads](/docs/guides/storage/uploads/standard-uploads#metadata) +- [Resumable Upload](/docs/guides/storage/uploads/resumable-uploads#metadata) + + + + + The metadata is immutable, meaning that once an object is uploaded with metadata, you cannot update the metadata. + You will currently need to update objects by re-uploading them with the new metadata. + + + + +## Retrieving Metadata + +To retrieve the metadata of an object, using the `info()` method. + +```javascript +const { data, error } = await supabase.from('bucket_name').info('path/your/object.png') + +console.log(data) + +// { +// id: "string", +// name: "string", +// version: "string", +// size: "number", +// content_type: "string", +// cache_control: "string" +// etag: "string" +// metadata: { +// custom_key: "custom_value" +// }, +// last_modified: "string" +// created_at: "string" +// } +``` \ No newline at end of file diff --git a/apps/docs/content/guides/storage/uploads/resumable-uploads.mdx b/apps/docs/content/guides/storage/uploads/resumable-uploads.mdx index 75692c6594c8f..939a2426c26ba 100644 --- a/apps/docs/content/guides/storage/uploads/resumable-uploads.mdx +++ b/apps/docs/content/guides/storage/uploads/resumable-uploads.mdx @@ -119,6 +119,22 @@ When uploading using the resumable upload endpoint, the storage server creates a This unique upload URL will be valid for **up to 24 hours**. If the upload is not completed within 24 hours, the URL will expire and you'll need to start the upload again. TUS client libraries typically create a new URL if the previous one expires. +### Metadata + +You can provide metadata when uploading a file. This metadata will be stored in the database and can be used to filter and search for files. The metadata object can contain any key-value pairs. + +```javascript +new tus.Upload(file, { + ..., + metadata: { + bucketName: bucketName, + objectName: fileName, + contentType: 'image/png', + cacheControl: 3600, + matadata: JSON.stringify({ key: 'value' }), + }, +``` + ### Concurrency When two or more clients upload to the same upload URL only one of them will succeed. The other clients will receive a `409 Conflict` error. Only 1 client can upload to the same upload URL at a time which prevents data corruption. diff --git a/apps/docs/content/guides/storage/uploads/standard-uploads.mdx b/apps/docs/content/guides/storage/uploads/standard-uploads.mdx index 9d383cb1e9f92..7648f2ef514ad 100644 --- a/apps/docs/content/guides/storage/uploads/standard-uploads.mdx +++ b/apps/docs/content/guides/storage/uploads/standard-uploads.mdx @@ -226,6 +226,18 @@ response = supabase.storage.from_('bucket_name').upload('file_path', file, { +## Metadata + +You can also add custom metadata to your file by passing the `metadata` option during upload. + +```javascript +await supabase.storage.from('bucket_name').upload('file_path', file, { + metadata: { + custom_key: 'custom_value', + }, +}) +``` + ## Concurrency When two or more clients upload a file to the same path, the first client to complete the upload will succeed and the other clients will receive a `400 Asset Already Exists` error. From 6bcecfb567a42485ec3fef5c76cb13c90cc2ec93 Mon Sep 17 00:00:00 2001 From: Fabrizio Date: Tue, 10 Sep 2024 15:16:18 +0200 Subject: [PATCH 2/4] Update apps/docs/content/guides/storage/management/metadata.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> --- apps/docs/content/guides/storage/management/metadata.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/apps/docs/content/guides/storage/management/metadata.mdx b/apps/docs/content/guides/storage/management/metadata.mdx index d35ce9f2e76ec..05b2f816e3729 100644 --- a/apps/docs/content/guides/storage/management/metadata.mdx +++ b/apps/docs/content/guides/storage/management/metadata.mdx @@ -10,7 +10,6 @@ sidebar_label: 'Object Metadata' Each object in a bucket can have metadata associated with it. Metadata is a set of key-value pairs that describe the object. You can use metadata to store information such as the object's content type, author, or any other custom data. - Each upload method in the Storage API accepts a `metadata` option that allows you to add custom metadata to the object. Please refer to the followings guides for more information on how to upload objects with metadata.: From 29c20b2a756de7b6cab3fa59f1c4270fcd222b81 Mon Sep 17 00:00:00 2001 From: Fabrizio Date: Tue, 10 Sep 2024 15:16:36 +0200 Subject: [PATCH 3/4] Update apps/docs/content/guides/storage/management/metadata.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> --- apps/docs/content/guides/storage/management/metadata.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/content/guides/storage/management/metadata.mdx b/apps/docs/content/guides/storage/management/metadata.mdx index 05b2f816e3729..d76ce9c8d54cc 100644 --- a/apps/docs/content/guides/storage/management/metadata.mdx +++ b/apps/docs/content/guides/storage/management/metadata.mdx @@ -11,7 +11,7 @@ Each object in a bucket can have metadata associated with it. Metadata is a set You can use metadata to store information such as the object's content type, author, or any other custom data. Each upload method in the Storage API accepts a `metadata` option that allows you to add custom metadata to the object. -Please refer to the followings guides for more information on how to upload objects with metadata.: +See the following guides for more information on how to upload objects with metadata: - [Standard Uploads](/docs/guides/storage/uploads/standard-uploads#metadata) - [Resumable Upload](/docs/guides/storage/uploads/resumable-uploads#metadata) From 1d96501171c87bf57d39bedb614563a0e3f9168f Mon Sep 17 00:00:00 2001 From: Fabrizio Date: Tue, 10 Sep 2024 15:16:44 +0200 Subject: [PATCH 4/4] Update apps/docs/content/guides/storage/management/metadata.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> --- apps/docs/content/guides/storage/management/metadata.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/content/guides/storage/management/metadata.mdx b/apps/docs/content/guides/storage/management/metadata.mdx index d76ce9c8d54cc..efd7dd53b2251 100644 --- a/apps/docs/content/guides/storage/management/metadata.mdx +++ b/apps/docs/content/guides/storage/management/metadata.mdx @@ -27,7 +27,7 @@ See the following guides for more information on how to upload objects with meta ## Retrieving Metadata -To retrieve the metadata of an object, using the `info()` method. +To retrieve the metadata of an object, use the `info()` method. ```javascript const { data, error } = await supabase.from('bucket_name').info('path/your/object.png')