Interface: StorageReader

server.StorageReader

An interface to read files from storage within Convex query functions.

Available as ctx.storage in queries (read-only), mutations, and actions.

Example

// Get a URL for a stored file:
const url = await ctx.storage.getUrl(storageId);
if (url) {
  // Use the URL (e.g., return it to the client)
}

// Get file metadata via the system table (preferred over deprecated getMetadata):
const metadata = await ctx.db.system.get("_storage", storageId);
// metadata: { _id, _creationTime, sha256, size, contentType? }

See

https://docs.convex.dev/file-storage

Hierarchy

• StorageReader

  ↳ StorageWriter

Methods

getUrl

▸ getUrl(storageId): Promise<null | string>

Get the URL for a file in storage by its Id<"_storage">.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

Example

const url = await ctx.storage.getUrl(storageId);

Parameters

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file to fetch from Convex storage.

Returns

Promise<null | string>

• A URL which fetches the file via an HTTP GET, or null if the file no longer exists.

Defined in

server/storage.ts:72

▸ getUrl<T>(storageId): Promise<null | string>

Deprecated

Passing a string is deprecated, use storage.getUrl(Id<"_storage">) instead.

Get the URL for a file in storage by its StorageId.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

Type parameters

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file to fetch from Convex storage.

Returns

Promise<null | string>

• A url which fetches the file via an HTTP GET, or null if it no longer exists.

Defined in

server/storage.ts:84

---

getMetadata

▸ getMetadata(storageId): Promise<null | FileMetadata>

Deprecated

Use ctx.db.system.get("_storage", storageId) instead, which returns equivalent metadata from the _storage system table (with a slightly different shape):

const metadata = await ctx.db.system.get("_storage", storageId);
// { _id, _creationTime, sha256, size, contentType? }

Get metadata for a file.

Parameters

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file.

Returns

Promise<null | FileMetadata>

• A FileMetadata object if found or null if not found.

Defined in

server/storage.ts:101

▸ getMetadata<T>(storageId): Promise<null | FileMetadata>

Deprecated

Use ctx.db.system.get("_storage", storageId) instead.

Get metadata for a file.

Type parameters

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file.

Returns

Promise<null | FileMetadata>

• A FileMetadata object if found or null if not found.

Defined in

server/storage.ts:111