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..efd7dd53b2251 --- /dev/null +++ b/apps/docs/content/guides/storage/management/metadata.mdx @@ -0,0 +1,51 @@ +--- +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. +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) + + + + + 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, use 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.