Python客户端库

supabase-py

本参考文档记录了 Supabase 的 Python 库 supabase-py 中可用的每个对象和方法。您可以使用 supabase-py 与您的 Postgres 数据库交互、监听数据库更改、调用 Deno Edge 函数、构建登录和用户管理功能以及管理大型文件。

安装

使用 PyPi 安装#

您可以通过终端安装 supabase-py。（适用于 Python > 3.8）

1
pip install supabase

初始化

您可以使用 create_client() 方法初始化一个新的 Supabase 客户端。

Supabase 客户端是您进入 Supabase 所有功能的入口点，也是与我们 Supabase 生态系统中的所有内容交互的最简单方法。

参数

supabase_url
必需
字符串
您在项目仪表板中创建新项目时提供的唯一 Supabase URL。
supabase_key
必需
字符串
您在项目仪表板中创建新项目时提供的唯一 Supabase Key。
options
可选
ClientOptions
用于更改 Auth 行为的选项。

1
import os
2
from supabase import create_client, Client
3
4
url: str = os.environ.get("SUPABASE_URL")
5
key: str = os.environ.get("SUPABASE_KEY")
6
supabase: Client = create_client(url, key)

获取数据

默认情况下，Supabase 项目返回最多 1,000 行数据。可以在您项目的 API 设置中更改此设置。建议将其保持较低，以限制意外或恶意请求的有效负载大小。您可以使用 range() 查询来分页您的数据。
select() 可以与过滤器结合使用
select() 可以与修饰符结合使用
apikey 如果您使用 Supabase 平台和应该避免作为列名，则是一个保留关键字。

参数

列
可选
字符串
要检索的列，默认为 *。
count
可选
CountMethod
用于获取返回的行数目的属性。

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .execute()
5
)

插入数据

参数

json
必需
dict, list
要插入的值。传递一个 dict 来插入单行，或传递一个 list 来插入多行。
count
可选
CountMethod
用于获取返回的行数目的属性。
returning
可选
ReturnMethod
“minimal” 或 “representation”。默认为 “representation”。
default_to_null
可选
bool
使缺失字段默认为 null。否则，使用列的默认值。仅适用于批量插入。

1
response = (
2
    supabase.table("planets")
3
    .insert({"id": 1, "name": "Pluto"})
4
    .execute()
5
)

更新数据

update() 始终应与过滤器结合使用，以定位您希望更新的项目。

参数

json
必需
dict, list
要插入的值。传递一个 dict 来插入单行，或传递一个 list 来插入多行。
count
可选
CountMethod
用于获取返回的行数目的属性。

1
response = (
2
    supabase.table("instruments")
3
    .update({"name": "piano"})
4
    .eq("id", 1)
5
    .execute()
6
)

更新或插入数据

要使用 upsert，必须在 values dict 中包含主键。

参数

json
必需
dict, list
要插入的值。传递一个 dict 来插入单行，或传递一个 list 来插入多行。
count
可选
CountMethod
用于获取返回的行数目的属性。
returning
可选
ReturnMethod
“minimal” 或 “representation”。默认为 “representation”。
ignore_duplicates
可选
bool
是否忽略重复行。
on_conflict
可选
字符串
指定要与 UNIQUE 约束一起使用的列。
default_to_null
可选
bool
使缺失字段默认为 null。否则，使用列的默认值。仅适用于批量插入。

1
response = (
2
    supabase.table("instruments")
3
    .upsert({"id": 1, "name": "piano"})
4
    .execute()
5
)

删除数据

delete() 始终应与过滤器结合使用，以定位您希望删除的项目。
如果您使用带有过滤器的 delete() 并且启用了 RLS，则只会删除通过 SELECT 策略可见的行。请注意，默认情况下没有行可见，因此您至少需要一个使行可见的 SELECT/ALL 策略。
当使用 delete().in_() 时，指定一个值数组以使用单个查询定位多个行。这对于批量删除具有共同标准的条目（例如按其 ID 删除用户）特别有用。确保您提供的数组准确表示您打算删除的所有记录，以避免意外删除数据。

参数

count
可选
CountMethod
用于获取返回的行数目的属性。
returning
可选
ReturnMethod
“minimal” 或 “representation”。默认为 “representation”。

1
response = (
2
    supabase.table("countries")
3
    .delete()
4
    .eq("id", 1)
5
    .execute()
6
)

调用 Postgres 函数

您可以将 Postgres 函数作为远程过程调用调用，即数据库中的逻辑，您可以从任何地方执行它。当逻辑很少更改时，函数很有用——例如用于密码重置和更新。

1
create or replace function hello_world() returns text as $$
2
  select 'Hello world';
3
$$ language sql;

参数

fn
必需
callable
要执行的存储过程调用。
params
可选
dict of any
传递到存储过程调用的参数。
get
可选
dict of any
如果设置为 true，则不会返回 data。如果您只需要计数，则很有用。
head
可选
dict of any
如果设置为 true，则以只读访问模式调用该函数。
count
可选
CountMethod
用于计算函数返回的行数的计数算法。仅适用于返回集合的函数。 "exact"：精确但缓慢的计数算法。在底层执行 COUNT(*)。 "planned"：近似但快速的计数算法。使用 Postgres 统计信息在底层。 "estimated"：对低数量使用精确计数，对高数量使用计划计数。

1
response = (
2
    supabase.rpc("hello_world")
3
    .execute()
4
)

使用过滤器

过滤器允许你仅返回匹配特定条件的行。

过滤器可用于 select()、update()、upsert() 和 delete() 查询。

如果 Postgres 函数返回表响应，您也可以应用过滤器。

1
# Correct
2
response = (
3
    supabase.table("instruments")
4
    .select("name, section_id")
5
    .eq("name", "flute")
6
    .execute()
7
)
8
9
# Incorrect
10
response = (
11
    supabase.table("instruments")
12
    .eq("name", "flute")
13
    .select("name, section_id")
14
    .execute()
15
)

列等于一个值

仅匹配 column 等于 value 的行。

参数

column
必需
字符串
要过滤的列
value
必需
any
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .eq("name", "Earth")
5
    .execute()
6
)

列不等于一个值

仅匹配 column 不等于 value 的行。

参数

column
必需
字符串
要过滤的列
value
必需
any
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .neq("name", "Earth")
5
    .execute()
6
)

列大于一个值

仅匹配 column 大于 value 的行。

参数

column
必需
字符串
要过滤的列
value
必需
any
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .gt("id", 2)
5
    .execute()
6
)

列大于或等于一个值

仅匹配 column 大于或等于 value 的行。

参数

column
必需
字符串
要过滤的列
value
必需
any
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .gte("id", 2)
5
    .execute()
6
)

列小于一个值

仅匹配 column 小于 value 的行。

参数

column
必需
字符串
要过滤的列
value
必需
any
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .lt("id", 2)
5
    .execute()
6
)

列小于或等于一个值

仅匹配 column 小于或等于 value 的行。

参数

column
必需
字符串
要过滤的列
value
必需
any
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .lte("id", 2)
5
    .execute()
6
)

列匹配一个模式

仅匹配 column 区分大小写地匹配 pattern 的行。

参数

column
必需
字符串
要应用过滤器的列名称
pattern
必需
字符串
要匹配的模式

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .like("name", "%Ea%")
5
    .execute()
6
)

列匹配一个不区分大小写的模式

仅匹配 column 不区分大小写地匹配 pattern 的行。

参数

column
必需
字符串
要应用过滤器的列名称
pattern
必需
字符串
要匹配的模式

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .ilike("name", "%ea%")
5
    .execute()
6
)

列是一个值

仅匹配 column IS value 的行。

参数

column
必需
字符串
要应用过滤器的列名称
value
必需
null | boolean
要匹配的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .is_("name", "null")
5
    .execute()
6
)

列在一个数组中

仅匹配 column 包含在 values 数组中的行。

参数

column
必需
字符串
要过滤的列
值
必需
array
要过滤的值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .in_("name", ["Earth", "Mars"])
5
    .execute()
6
)

列包含数组中的每个元素

仅适用于 jsonb、数组和范围列。仅匹配 column 包含 value 中出现的每个元素的行。

参数

column
必需
字符串
要过滤的列
值
必需
object
要使用 jsonb、数组或范围过滤的 jsonb、数组或范围值

1
response = (
2
    supabase.table("issues")
3
    .select("*")
4
    .contains("tags", ["is:open", "priority:low"])
5
    .execute()
6
)

包含在值中

仅适用于 jsonb、数组和范围列。仅匹配 column 中的每个元素都包含在 value 中。

参数

column
必需
字符串
要过滤的 jsonb、数组或范围列
value
必需
object
要使用 jsonb、数组或范围过滤的 jsonb、数组或范围值

1
response = (
2
    supabase.table("classes")
3
    .select("name")
4
    .contained_by("days", ["monday", "tuesday", "wednesday", "friday"])
5
    .execute()
6
)

大于一个范围

仅适用于范围列。仅匹配 column 中的每个元素都大于 range 中的任何元素。

参数

column
必需
字符串
要过滤的范围列
range
必需
array
要过滤的范围

1
response = (
2
    supabase.table("reservations")
3
    .select("*")
4
    .range_gt("during", ["2000-01-02 08:00", "2000-01-02 09:00"])
5
    .execute()
6
)

大于或等于一个范围

仅适用于范围列。仅匹配 column 中的每个元素都包含在 range 中或大于 range 中的任何元素。

参数

column
必需
字符串
要过滤的范围列
range
必需
字符串
要过滤的范围

1
response = (
2
    supabase.table("reservations")
3
    .select("*")
4
    .range_gte("during", ["2000-01-02 08:30", "2000-01-02 09:30"])
5
    .execute()
6
)

小于一个范围

仅适用于范围列。仅匹配 column 中的每个元素都小于 range 中的任何元素。

参数

column
必需
字符串
要过滤的范围列
range
必需
array
要过滤的范围

1
response = (
2
    supabase.table("reservations")
3
    .select("*")
4
    .range_lt("during", ["2000-01-01 15:00", "2000-01-01 16:00"])
5
    .execute()
6
)

小于或等于一个范围

仅适用于范围列。仅匹配 column 中的每个元素都小于 range 中的任何元素。

参数

column
必需
字符串
要过滤的范围列
range
必需
array
要过滤的范围

1
response = (
2
    supabase.table("reservations")
3
    .select("*")
4
    .range_lte("during", ["2000-01-01 14:00", "2000-01-01 16:00"])
5
    .execute()
6
)

与范围互斥

仅适用于范围列。仅匹配 column 与 range 互斥，并且两者之间没有元素。

参数

column
必需
字符串
要过滤的范围列
range
必需
array
要过滤的范围

1
response = (
2
    supabase.table("reservations")
3
    .select("*")
4
    .range_adjacent("during", ["2000-01-01 12:00", "2000-01-01 13:00"])
5
    .execute()
6
)

具有共同元素

仅适用于数组和范围列。仅匹配 column 和 value 具有共同元素。

参数

column
必需
字符串
要过滤的数组或范围列
value
必需
Iterable[Any]
要过滤的数组或范围值

1
response = (
2
    supabase.table("issues")
3
    .select("title")
4
    .overlaps("tags", ["is:closed", "severity:high"])
5
    .execute()
6
)

匹配一个字符串

仅适用于文本和 tsvector 列。仅匹配 column 在 query 中匹配查询字符串的行。

有关更多信息，请参阅 Postgres 全文搜索。

参数

column
必需
字符串
要过滤的文本或 tsvector 列
query
必需
字符串
要匹配的查询文本
options
可选
object
命名参数

1
response = (
2
    supabase.table("texts")
3
    .select("content")
4
    .text_search(
5
        "content",
6
        "'eggs' & 'ham'",
7
        options={"config": "english"},
8
    )
9
    .execute()
10
)

匹配关联值

仅匹配 query 键中的每个列都等于其关联值的行。多个 .eq() 的简写。

参数

query
必需
dict
用于过滤的对象，列名作为键映射到其过滤值

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .match({"id": 2, "name": "Earth"})
5
    .execute()
6
)

不匹配过滤器

not_ 期望您使用原始 PostgREST 语法来获取过滤器的值。

1
.not_.in_('id', '(5,6,7)')  # Use `()` for `in` filter
2
.not_.contains('arraycol', '{"a","b"}')  # Use `{}` for array values

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .not_.is_("name", "null")
5
    .execute()
6
)

匹配至少一个过滤器

or_() 期望您使用原始 PostgREST 语法来获取过滤器名称和值。

1
.or_('id.in.(5,6,7), arraycol.cs.{"a","b"}')  # Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
2
.or_('id.in.(5,6,7), arraycol.cd.{"a","b"}')  # Use `cd` for `containedBy()`

参数

filters
必需
字符串
要使用的过滤器，遵循 PostgREST 语法
reference_table
可选
字符串
将其设置为过滤引用表而不是父表

1
response = (
2
    supabase.table("planets")
3
    .select("name")
4
    .or_("id.eq.2,name.eq.Mars")
5
    .execute()
6
)

匹配过滤器

filter() 期望您使用原始 PostgREST 语法来获取过滤器的值。

1
.filter('id', 'in', '(5,6,7)')  # Use `()` for `in` filter
2
.filter('arraycol', 'cs', '{"a","b"}')  # Use `cs` for `contains()`, `{}` for array values

参数

column
必需
字符串
要过滤的列
operator
可选
字符串
要使用的运算符，遵循 PostgREST 语法
value
可选
any
要过滤的值，遵循 PostgREST 语法

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .filter("name", "in", '("Mars","Tatooine")')
5
    .execute()
6
)

使用修饰符

过滤器在行级别上工作——它们允许您仅返回匹配特定条件的行，而不会更改行的形状。修饰符是所有不符合该定义的内容——允许您更改响应的格式（例如，返回 CSV 字符串）。

修饰符必须在过滤器之后指定。某些修饰符仅适用于返回行的查询（例如，select() 或返回表响应的函数的 rpc()）。

对结果进行排序

按 column 对查询结果进行排序。

参数

column
必需
字符串
要排序的列
desc
可选
bool
是否应按降序对行进行排序。
foreign_table
可选
字符串
要排序其结果的外表名称。
nullsfirst
可选
bool
按显示空值优先的顺序排序

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .order("name", desc=True)
5
    .execute()
6
)

限制返回的行数

参数

size
必需
number
要返回的最大行数
foreign_table
可选
字符串
将其设置为限制外表的行而不是父表。

1
response = (
2
    supabase.table("planets")
3
    .select("name")
4
    .limit(1)
5
    .execute()
6
)

将查询限制在一个范围内

通过从偏移量（start）开始并结束于偏移量（end）来限制查询结果。仅返回此范围内的记录。这尊重查询顺序，如果没有排序子句，则范围的行为可能不可预测。

start 和 end 值都是从零开始的并且包含在内：range(1, 3) 将包含查询的第二、第三和第四行。

参数

start
必需
number
限制结果的起始索引。
end
必需
number
限制结果的最后一个索引。
foreign_table
可选
字符串
将其设置为限制外表的行而不是父表。

1
response = (
2
    supabase.table("planets")
3
    .select("name")
4
    .range(0, 1)
5
    .execute()
6
)

检索一行数据

将 data 作为单个对象而不是对象数组返回。

1
response = (
2
    supabase.table("planets")
3
    .select("name")
4
    .limit(1)
5
    .single()
6
    .execute()
7
)

检索零行或一行数据

将 data 作为单个对象而不是对象数组返回。

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .eq("name", "Earth")
5
    .maybe_single()
6
    .execute()
7
)

检索为 CSV

将 data 作为 CSV 格式的字符串返回。

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .csv()
5
    .execute()
6
)

使用 explain

为了调试慢查询，你可以使用 explain() 方法获取查询的 Postgres EXPLAIN 执行计划。这适用于任何查询，甚至适用于 rpc() 或写入。

Explain 默认情况下未启用，因为它可能会泄露数据库中的敏感信息。最好仅在测试环境中使用，但如果您希望在生产环境中使用，可以通过使用 `pre-request` 函数提供额外的保护。

请遵循性能调试指南以在您的项目上启用此功能。

参数

wal
可选
boolean
如果为 true，则包含有关 WAL 记录生成的信息。
verbose
可选
boolean
如果为 true，将返回查询标识符，并且 data 将包含查询的输出列。
settings
可选
boolean
如果为 true，则包含有关影响查询计划的配置参数的信息。
format
可选
boolean
输出的格式，可以是 "text"（默认值）或 "json"。
format
可选
"text" | "json"
输出的格式，可以是 "text"（默认值）或 "json"。
buffers
可选
boolean
如果为 true，则包含有关缓冲区使用情况的信息。
analyze
可选
boolean
如果为 true，则将执行查询并返回实际运行时间。

1
response = (
2
    supabase.table("planets")
3
    .select("*")
4
    .explain()
5
    .execute()
6
)

概述

可以通过 supabase.auth 命名空间访问身份验证方法。
默认情况下，supabase 客户端将 persist_session 设置为 true 并尝试将会话存储在内存中。
发送的任何电子邮件链接和一次性密码 (OTP) 都有默认的 24 小时有效期。我们有以下速率限制以防止暴力攻击。
访问令牌的有效期可以在您的项目身份验证设置中的“JWT 有效期限制”字段中设置。刷新令牌永不过期，并且只能使用一次。

创建新用户

默认情况下，用户需要在登录前验证其电子邮件地址。要关闭此功能，请在您的项目中禁用 **确认电子邮件**。
**确认电子邮件** 确定用户在注册后是否需要确认其电子邮件地址。
- 如果启用了 **确认电子邮件**，则会返回一个 `user`，但 `session` 为 null。
- 如果禁用了 **确认电子邮件**，则会同时返回 `user` 和 `session`。
默认情况下，当用户确认他们的电子邮件地址时，他们会被重定向到 SITE_URL。您可以在您的项目中修改您的 SITE_URL 或添加额外的重定向 URL。
如果为已确认的用户调用 sign_up()
- 当在您的项目中同时启用 **确认电子邮件** 和 **确认电话**（即使电话提供程序已禁用）时，将返回一个混淆/虚假的用户对象。
- 当 **确认电子邮件** 或 **确认电话**（即使电话提供程序已禁用）中的任何一个被禁用时，将返回错误消息 `User already registered`。
要获取当前登录的用户，请参阅 get_user()。

参数

凭据
必需
SignUpWithPasswordCredentials

创建匿名用户

返回一个匿名用户
建议为匿名注册设置验证码以防止滥用。您可以在 `options` 参数中传递验证码令牌。

参数

凭据
必需
SignInAnonymouslyCredentials

登录用户

使用电子邮件和密码或电话和密码登录现有用户。

需要电子邮件和密码或电话号码和密码。

参数

凭据SignInWithPasswordCredentials

使用 ID Token 登录 (原生登录)

允许使用 OIDC ID 令牌进行登录。使用的身份验证提供程序应已启用并配置。

参数

凭据SignInWithIdTokenCredentials

通过 OTP 登录用户

需要电子邮件或电话号码。
此方法用于无密码登录，其中 OTP 会发送到用户的电子邮件或电话号码。
如果用户不存在，sign_in_with_otp() 将代替注册用户。要限制此行为，您可以将 SignInWithPasswordlessCredentials.options 中的 should_create_user 设置为 false。
如果您使用的是电子邮件，您可以配置是否希望用户接收 magiclink 或 OTP。
如果您使用的是电话号码，您可以配置是否希望用户接收 OTP。
magic link 的目标 URL 由 SITE_URL 确定。
请参阅重定向 URL 和通配符，以将其他重定向 URL 添加到您的项目中。
magic link 和 OTP 共享相同的实现。要向用户发送一次性代码而不是 magic link，请修改 magic link 电子邮件模板，以包含 {{ .Token }} 而不是 {{ .ConfirmationURL }}。

参数

凭据SignInWithPasswordCredentials

1
response = supabase.auth.sign_in_with_otp(
2
    {
3
        "email": "email@example.com",
4
        "options": {
5
            "email_redirect_to": "https://example.com/welcome",
6
        },
7
    }
8
)

通过 OAuth 登录用户

此方法用于使用第三方提供程序登录。
Supabase 支持许多不同的第三方提供程序。

参数

凭据
必需
SignInWithOAuthCredentials

通过 SSO 登录用户

在您可以使用此方法之前，您需要建立与身份提供程序的连接。使用 CLI 命令来执行此操作。
如果您已将电子邮件域与身份提供程序关联，则可以使用 `domain` 属性启动登录流程。
如果您需要使用不同的方式启动与身份提供程序的身份验证流程，可以使用 provider_id 属性。例如
- 将特定的用户电子邮件地址与身份提供程序映射。
- 使用不同的提示来识别用户要使用的身份提供程序，例如公司特定的页面、IP 地址或其他跟踪信息。

参数

参数SignInWithSSOCredentials

从经过验证的 JWT 获取用户声明

通过首先对照服务器的 JSON Web Key Set 端点 /.well-known/jwks.json（通常会缓存）验证 JWT，来提取访问令牌中存在的 JWT 声明。优于 get_user，后者始终将请求发送到 Auth 服务器以获取每个 JWT。

参数

jwt
可选
字符串
您希望验证的特定 JWT（可选），而不是您可以从 get_session 获取的 JWT。
jwks
可选
JWKSet
如果设置，此 JSON Web Key Set 将优先于服务器上可用的缓存值。

1
response = supabase.auth.get_claims()

注销用户

为了使用 sign_out() 方法，用户首先需要登录。
默认情况下，sign_out() 使用全局范围，这会注销用户登录的所有其他会话。
由于 Supabase Auth 使用 JWT 进行身份验证，因此访问令牌 JWT 在其过期之前有效。当用户注销时，Supabase 会撤销刷新令牌并从客户端删除 JWT。这不会撤销 JWT，它在到期之前仍然有效。

参数

options
可选
SignOutOptions

1
response = supabase.auth.sign_out()

发送密码重置请求

密码重置流程包含 2 个主要步骤：(i) 允许用户通过密码重置链接登录；(ii) 更新用户的密码。
reset_password_for_email() 仅将密码重置链接发送到用户的电子邮件。要更新用户的密码，请参阅 update_user()。
当用户单击电子邮件中的重置链接时，他们会被重定向回您的应用程序。您可以使用 redirectTo 参数配置用户被重定向到的 URL。请参阅重定向 URL 和通配符，以将其他重定向 URL 添加到您的项目中。
在用户成功重定向后，提示他们输入新密码并调用 update_user()

1
response = supabase.auth.update_user(
2
    {"password": new_password}
3
)

参数

email
必需
字符串
用户的电子邮件地址。
options
可选
object

1
supabase.auth.reset_password_for_email(
2
    email,
3
    {
4
        "redirect_to": "https://example.com/update-password",
5
    }
6
)

通过 OTP 验证并登录

verify_otp 方法接受不同的验证类型。如果使用电话号码，则类型可以是 sms 或 phone_change。如果使用电子邮件地址，则类型可以是以下之一：email、recovery、invite 或 email_change（signup 和 magiclink 类型已弃用）。
使用的验证类型应根据在 verify_otp 之前调用的相应 auth 方法来确定，以注册/登录用户。
TokenHash 包含在电子邮件模板中，可用于登录。您可能希望在服务器端身份验证的 PKCE 流程中使用哈希值。请阅读基于密码的身份验证指南，了解更多详细信息。

参数

参数VerifyOtpParams

获取会话

此方法检索当前的本地会话（即内存中）。
会话包含一个签名的 JWT 和未编码的会话数据。
由于未编码的会话数据是从本地存储介质检索的，不要依赖它作为服务器上受信任数据源。它可能被发送者篡改。如果您需要经过验证的可信用户数据，请调用 get_user。
如果会话的访问令牌已过期，此方法将使用刷新令牌获取新的会话。

1
response = supabase.auth.get_session()

获取新的会话

返回新的会话，无论其是否过期。接受可选的刷新令牌。如果未传递，refresh_session() 将尝试从 get_session() 中检索它。如果当前会话的刷新令牌无效，将抛出错误。

此方法将刷新会话，无论当前会话是否过期。

参数

refresh_token
可选
字符串

1
response = supabase.auth.refresh_session()

获取用户

此方法从数据库而不是本地会话中获取用户对象。
此方法对于检查用户是否已授权很有用，因为它会在服务器上验证用户的访问令牌 JWT。
用户模型包含以下字段（自 v2.28.0 起）：is_sso_user (bool，默认为 False)、deleted_at (可选字符串) 和 banned_until (可选字符串)，以及现有字段。

参数

jwt
可选
字符串
接受可选的访问令牌 JWT。如果未提供 JWT，则使用当前会话中的 JWT。

1
response = supabase.auth.get_user()

更新用户

为了使用 update_user() 方法，用户首先需要登录。
默认情况下，电子邮件更新会向用户的当前电子邮件和新电子邮件发送确认链接。要仅向用户的新的电子邮件发送确认链接，请在您项目的电子邮件身份验证提供程序设置中禁用 安全电子邮件更改。

参数

attributes
必需
UserAttributes
options
可选
object

1
response = supabase.auth.update_user(
2
    {"email": "new@email.com"}
3
)

获取与用户关联的身份

获取链接到用户的所有身份。

需要登录的用户才能调用 get_user_identities()。

1
response = supabase.auth.get_user_identities()

将身份与用户关联

必须从您的项目身份验证设置中启用 **启用手动链接** 选项。
需要登录的用户才能调用 link_identity()。
如果候选身份已链接到现有用户或另一个用户，link_identity() 将失败。
如果在服务器上运行 link_identity，您应该处理重定向。

参数

凭据
必需
SignInWithOAuthCredentials

1
response = supabase.auth.link_identity(
2
    {"provider": "github"}
3
)

将身份从用户取消关联

必须从您的项目身份验证设置中启用 **启用手动链接** 选项。
需要登录的用户才能调用 unlink_identity()。
用户必须至少拥有 2 个身份才能取消关联一个身份。
要取消关联的身份必须属于该用户。

参数

identity
必需
UserIdentity

1
# retrieve all identities linked to a user
2
response = supabase.auth.get_user_identities()
3
4
# find the google identity
5
google_identity = list(
6
    filter(lambda identity: identity.provider == "google", response.identities)
7
).pop()
8
9
# unlink the google identity
10
response = supabase.auth.unlink_identity(google_identity)

发送密码重新认证 nonce

此方法与 update_user() 结合使用，当需要更新用户的密码时。
如果您要求用户在更新密码之前重新进行身份验证，则需要在您的项目电子邮件提供程序设置中启用 安全密码更改 选项。
只有在启用 安全密码更改 并且用户 最近没有登录 的情况下，用户才需要在更新密码之前重新进行身份验证。如果会话是在过去 24 小时内创建的，则认为用户最近已登录。
此方法会将 nonce 发送到用户的电子邮件。如果用户没有确认的电子邮件地址，该方法会将 nonce 发送到用户的确认的电话号码。

1
response = supabase.auth.reauthenticate()

重新发送 OTP

通过再次调用 reset_password_for_email() 方法，可以重新发送密码重置电子邮件。
可以通过再次调用 sign_in_with_otp() 方法重新发送无密码登录。
可以通过再次调用 reset_password_for_email() 方法重新发送密码恢复电子邮件。
此方法仅会在正在进行初始注册、电子邮件更改或电话号码更改请求时，才会向用户重新发送电子邮件或电话 OTP。
您可以使用 email_redirect_to 选项在重新发送电子邮件链接时指定重定向 URL。

参数

凭据
必需
ResendCredentials

1
response = supabase.auth.resend(
2
    {
3
        "type": "signup",
4
        "email": "email@example.com",
5
        "options": {
6
            "email_redirect_to": "https://example.com/welcome",
7
        },
8
    }
9
)

设置会话数据

从当前会话设置会话数据。如果当前会话已过期，setSession 将负责刷新它以获取新的会话。如果当前会话中的刷新令牌或访问令牌无效，将抛出错误。

此方法使用 access_token 和 refresh_token 设置会话。
如果成功，将发出 SIGNED_IN 事件。

参数

access_token
必需
字符串
refresh_token
必需
字符串

1
response = supabase.auth.set_session(access_token, refresh_token)

将授权码交换为会话

通过交换 PKCE 流程期间发出的 Auth Code 登录现有用户。

当客户端选项中的 flow_type 设置为 pkce 时使用。

参数

auth_code
必需
字符串

1
response = supabase.auth.exchange_code_for_session(
2
    {"auth_code": "34e770dd-9ff9-416c-87fa-43b31d7ef225"}
3
)

认证 MFA

本节包含通常用于多因素身份验证 (MFA) 的方法，并在 supabase.auth.mfa 命名空间下调用。

目前，我们仅支持基于时间的 One-Time Password (TOTP) 作为第二个因素。我们不支持恢复代码，但允许用户注册超过 1 个 TOTP 因素，上限为 10 个。

拥有第二个 TOTP 因素用于恢复，可以减轻用户存储恢复代码的负担。它还可以减少攻击面，因为通常会生成多个恢复代码，而不仅仅是 1 个备份 TOTP 因素。

注册因素

目前，totp 是唯一支持的 factor_type。返回的 id 应用于创建挑战。
要创建挑战，请参阅 mfa.challenge()。
要验证挑战，请参阅 mfa.verify()。
要一步创建和验证挑战，请参阅 mfa.challenge_and_verify()。

1
response = supabase.auth.mfa.enroll(
2
    {
3
        "factor_type": "totp",
4
        "friendly_name": "your_friendly_name",
5
    }
6
)

创建挑战

在创建挑战之前，需要一个已注册的因素。
要验证挑战，请参阅 mfa.verify()。

1
response = supabase.auth.mfa.challenge(
2
    {"factor_id": "34e770dd-9ff9-416c-87fa-43b31d7ef225"}
3
)

验证挑战

要验证挑战，请先创建挑战。

1
response = supabase.auth.mfa.verify(
2
    {
3
        "factor_id": "34e770dd-9ff9-416c-87fa-43b31d7ef225",
4
        "challenge_id": "4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15",
5
        "code": "123456",
6
    }
7
)

创建并验证挑战

在调用 challengeAndVerify() 之前，需要一个已注册的因素。
执行 mfa.challenge() 和 mfa.verify() 在一步中。

1
response = supabase.auth.mfa.challenge_and_verify(
2
    {
3
        "factor_id": "34e770dd-9ff9-416c-87fa-43b31d7ef225",
4
        "code": "123456",
5
    }
6
)

取消注册因素

1
response = supabase.auth.mfa.unenroll(
2
    {"factor_id": "34e770dd-9ff9-416c-87fa-43b31d7ef225"}
3
)

获取身份验证器保证级别

身份验证器保证级别 (AAL) 是身份验证机制强度的度量。
在 Supabase 中，具有 aal1 的 AAL 指的是第一因素身份验证，例如电子邮件和密码或 OAuth 登录，而 aal2 指的是第二因素身份验证，例如基于时间的一次性密码 (TOTP)。
如果用户具有已验证的因素，则 next_level 字段将返回 aal2，否则，它将返回 aal1。

1
response = supabase.auth.mfa.get_authenticator_assurance_level()

认证 Admin

supabase.auth.admin 命名空间下的任何方法都需要一个 service_role 密钥。
这些方法被认为是管理方法，应在受信任的服务器上调用。切勿在浏览器中公开你的 service_role 密钥。

1
from supabase import create_client
2
from supabase.lib.client_options import ClientOptions
3
4
supabase = create_client(
5
    supabase_url,
6
    service_role_key,
7
    options=ClientOptions(
8
        auto_refresh_token=False,
9
        persist_session=False,
10
    )
11
)
12
13
# Access auth admin api
14
admin_auth_client = supabase.auth.admin

获取用户

根据用户的 ID 从数据库中获取用户对象。
get_user_by_id() 方法需要用户的 ID，该 ID 映射到 auth.users.id 列。

参数

uid
必需
字符串
用户的唯一标识符

此函数只能在服务器上调用。切勿在浏览器中公开你的 service_role 密钥。

1
response = supabase.auth.admin.get_user_by_id(1)

列出所有用户

默认情况下，每页返回 50 个用户。

参数

params
可选
PageParams
一个对象，支持将 page 和 per_page 作为数字，以更改分页结果。

1
response = supabase.auth.admin.list_users()

创建用户

要确认用户的电子邮件地址或电话号码，请将 email_confirm 或 phone_confirm 设置为 true。两个参数都默认为 false。
create_user() 不会向用户发送确认电子邮件。如果你想发送电子邮件邀请，可以使用 invite_user_by_email()。
如果您确定创建用户的电子邮件或电话号码是合法的且经过验证的，则可以将 email_confirm 或 phone_confirm 参数设置为 true。

参数

attributes
必需
AdminUserAttributes

1
response = supabase.auth.admin.create_user(
2
    {
3
        "email": "user@email.com",
4
        "password": "password",
5
        "user_metadata": {"name": "Yoda"},
6
    }
7
)

删除用户

删除用户。需要 service_role 密钥。

delete_user() 方法需要用户的 ID，该 ID 映射到 auth.users.id 列。

参数

id
必需
字符串
你要删除的用户 ID。
should_soft_delete
可选
boolean
如果为 true，则用户将被软删除（将 deleted_at 设置为当前时间戳并禁用他们的帐户，同时保留他们的数据）从 auth 模式。默认值为 false，以保持向后兼容性。

此函数只能在服务器上调用。切勿在浏览器中公开你的 service_role 密钥。

1
supabase.auth.admin.delete_user(
2
    "715ed5db-f090-4b8c-a067-640ecee36aa0"
3
)

发送电子邮件邀请链接

向电子邮件地址发送邀请链接。

向用户的电子邮件地址发送邀请链接。
invite_user_by_email() 方法通常由管理员用于邀请用户加入应用程序。
请注意，使用 invite_user_by_email 不支持 PKCE。这是因为发起邀请的浏览器通常与接受邀请的浏览器不同，这使得提供 PKCE 流程所需的安全性保证变得困难。

参数

email
必需
字符串
用户的电子邮件地址。
options
可选
InviteUserByEmailOptions

1
response = supabase.auth.admin.invite_user_by_email("email@example.com")

生成电子邮件链接

以下类型可以传递到 generate_link()：signup、magiclink、invite、recovery、email_change_current、email_change_new、phone_change。
只有在你的项目电子邮件身份验证提供程序设置中启用了“安全电子邮件更改”时，generate_link() 才会为 email_change_email 生成电子邮件链接。
generate_link() 处理 signup、invite 和 magiclink 的用户创建。

参数

paramsGenerateLinkParams

更新用户

参数

uid
必需
字符串
attributes
必需
AdminUserAttributes
你要更新的数据。

此函数只能在服务器上调用。切勿在浏览器中公开你的 service_role 密钥。

1
response = supabase.auth.admin.update_user_by_id(
2
    "11111111-1111-1111-1111-111111111111",
3
    {
4
        "email": "new@email.com",
5
    }
6
)

删除用户的因素

删除用户的一个因素。如果删除的因素已验证，这将使用户退出所有活动会话。

参数

params
必需
AuthMFAAdminDeleteFactorParams

1
response = supabase.auth.admin.mfa.delete_factor(
2
    {
3
        "id": "34e770dd-9ff9-416c-87fa-43b31d7ef225",
4
        "user_id": "a89baba7-b1b7-440f-b4bb-91026967f66b"
5
    }
6
)

OAuth 管理

OAuth 2.1 客户端管理端点可通过 supabase.auth.admin.oauth 命名空间提供。
这些方法需要 service_role 密钥，并且只能在服务器端调用。
仅当 Supabase Auth 中启用了 OAuth 2.1 服务器时才相关。
这是一个 alpha 功能，未来可能会更改。

列出 OAuth 客户端

列出 OAuth 客户端，并提供可选的分页。

需要 service_role 密钥。
仅当启用 OAuth 2.1 服务器时可用。
这是一个 alpha 功能，未来可能会更改。

参数

params
可选
PageParams
可选的分页参数。

1
response = supabase.auth.admin.oauth.list_clients()

获取 OAuth 客户端

通过 ID 检索 OAuth 客户端的详细信息。

需要 service_role 密钥。
仅当启用 OAuth 2.1 服务器时可用。
这是一个 alpha 功能，未来可能会更改。

参数

client_id
必需
字符串
要检索的 OAuth 客户端的 ID。

1
response = supabase.auth.admin.oauth.get_client("client-id")

创建 OAuth 客户端

创建一个新的 OAuth 客户端。

需要 service_role 密钥。
仅当启用 OAuth 2.1 服务器时可用。
这是一个 alpha 功能，未来可能会更改。

参数

params
必需
CreateOAuthClientParams
创建新的 OAuth 客户端的参数。

1
response = supabase.auth.admin.oauth.create_client(
2
    {
3
        "name": "My OAuth Client",
4
        "redirect_uris": ["https://example.com/callback"]
5
    }
6
)

更新 OAuth 客户端

更新现有的 OAuth 客户端。

需要 service_role 密钥。
仅当启用 OAuth 2.1 服务器时可用。
这是一个 alpha 功能，未来可能会更改。

参数

client_id
必需
字符串
要更新的 OAuth 客户端的 ID。
params
必需
UpdateOAuthClientParams
更新 OAuth 客户端的参数。

1
response = supabase.auth.admin.oauth.update_client(
2
    "client-id",
3
    {
4
        "name": "Updated OAuth Client",
5
        "redirect_uris": ["https://example.com/callback", "https://example.com/callback2"]
6
    }
7
)

删除 OAuth 客户端

删除 OAuth 客户端。

需要 service_role 密钥。
仅当启用 OAuth 2.1 服务器时可用。
这是一个 alpha 功能，未来可能会更改。

参数

client_id
必需
字符串
要删除的 OAuth 客户端的 ID。

1
supabase.auth.admin.oauth.delete_client("client-id")

重新生成客户端密钥

重新生成 OAuth 客户端的客户端密钥。

需要 service_role 密钥。
仅当启用 OAuth 2.1 服务器时可用。
这是一个 alpha 功能，未来可能会更改。

参数

client_id
必需
字符串
OAuth 客户端的 ID。

1
response = supabase.auth.admin.oauth.regenerate_client_secret("client-id")

调用 Supabase 边缘函数。

调用 Supabase 函数。

需要 Authorization 标头。
当你将主体传递给你的函数时，我们会自动为 Blob、ArrayBuffer、File、FormData 和 String 附加 Content-Type 标头。如果它不匹配任何这些类型，我们会假定有效负载是 json，对其进行序列化并将 Content-Type 标头附加为 application/json。你可以通过传递你自己的 Content-Type 标头来覆盖此行为。

1
response = supabase.functions.invoke(
2
    "hello-world",
3
    invoke_options={
4
        "body": {"name": "Functions"},
5
    },
6
)

概述

Python 中的实时功能仅适用于异步客户端。你可以使用 acreate_client() 方法初始化一个新的 Supabase 客户端。

某些实时方法是异步的，必须等待。确保在 async 函数中调用这些方法。
在以下实时示例中，某些方法被等待。这些应该包含在 async 函数中。
当需要在同步上下文中使用的异步方法时，例如 .subscribe() 的回调，请使用 asyncio.create_task() 来安排协程。这就是为什么 acreate_client 示例包含 asyncio 的导入。

1
import os
2
import asyncio
3
from supabase import acreate_client, AsyncClient
4
5
url: str = os.environ.get("SUPABASE_URL")
6
key: str = os.environ.get("SUPABASE_KEY")
7
8
async def create_supabase():
9
  supabase: AsyncClient = await acreate_client(url, key)
10
  return supabase

订阅频道

默认情况下，广播和存在性对所有项目都已启用。
当你附加存在性回调（on_presence_sync()、on_presence_join() 或 on_presence_leave()）时，存在性会自动启用。如果你将存在性回调添加到已经加入的频道，该频道将自动使用启用存在性重新订阅。
默认情况下，由于数据库性能和安全问题，对数据库更改的侦听在新项目中是禁用的。你可以通过管理实时的复制来启用它。
你可以通过将表的 REPLICA IDENTITY 设置为 FULL（例如，ALTER TABLE your_table REPLICA IDENTITY FULL;）来接收更新和删除的“先前”数据。
行级安全性不适用于删除语句。当启用 RLS 并且复制标识设置为 full 时，仅将主键发送给客户端。

1
channel = supabase.channel("room1")
2
3
def on_subscribe(status, err):
4
    if status == RealtimeSubscribeStates.SUBSCRIBED:
5
        asyncio.create_task(channel.send_broadcast(
6
            "cursor-pos",
7
            {"x": random.random(), "y": random.random()}
8
        ))
9
10
def handle_broadcast(payload):
11
    print("Cursor position received!", payload)
12
13
await channel.on_broadcast(event="cursor-pos", callback=handle_broadcast).subscribe(on_subscribe)

取消订阅频道

删除频道是维护项目实时服务性能以及数据库性能的好方法（如果你正在侦听 Postgres 更改）。Supabase 会在客户端断开连接 30 秒后自动处理清理，但未使用的频道可能会导致更多客户端同时订阅而导致性能下降。

1
await supabase.remove_channel(myChannel)

取消订阅所有频道

删除频道是维护项目实时服务性能以及数据库性能的好方法（如果你正在侦听 Postgres 更改）。Supabase 会在客户端断开连接 30 秒后自动处理清理，但未使用的频道可能会导致更多客户端同时订阅而导致性能下降。

1
await supabase.remove_all_channels()

获取所有频道

1
channels = supabase.get_channels()

广播消息

向连接到频道的客户端广播消息。

1
channel = supabase.channel("room1")
2
3
def on_subscribe(status, err):
4
    if status == RealtimeSubscribeStates.SUBSCRIBED:
5
        asyncio.create_task(channel.send_broadcast('cursor-pos', {"x": random.random(), "y": random.random()}))
6
7
await channel.subscribe(on_subscribe)

文件存储

本节包含处理文件存储桶的方法。

列出所有存储桶

检索现有项目中的所有存储存储桶的详细信息。

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

1
response = supabase.storage.list_buckets()

检索存储桶

检索现有的存储存储桶的详细信息。

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
你要检索的存储桶的唯一标识符。

1
response = supabase.storage.get_bucket("avatars")

创建存储桶

创建一个新的存储存储桶

所需的 RLS 策略权限
- buckets 表权限：insert
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
你要创建的存储桶的唯一标识符。
options
必需
CreateOrUpdateBucketOptions

1
response = (
2
    supabase.storage
3
    .create_bucket(
4
        "avatars",
5
        options={
6
            "public": False,
7
            "allowed_mime_types": ["image/png"],
8
            "file_size_limit": 1024,
9
        }
10
    )
11
)

清空存储桶

删除单个存储桶中的所有对象。

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：select 和 delete
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
你要清空的存储桶的唯一标识符。

1
response = supabase.storage.empty_bucket("avatars")

更新存储桶

更新存储存储桶

所需的 RLS 策略权限
- buckets 表权限：select 和 update
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
你要创建的存储桶的唯一标识符。
options
必需
CreateOrUpdateBucketOptions

1
response = (
2
    supabase.storage
3
    .update_bucket(
4
        "avatars",
5
        options={
6
            "public": False,
7
            "allowed_mime_types": ["image/png"],
8
            "file_size_limit": 1024,
9
        }
10
    )
11
)

删除存储桶

删除现有的存储桶。如果存储桶内存在现有对象，则无法删除存储桶。你必须首先 empty() 存储桶。

所需的 RLS 策略权限
- buckets 表权限：select 和 delete
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
你要删除的存储桶的唯一标识符。

1
response = supabase.storage.delete_bucket("avatars")

上传文件

将文件上传到现有的存储桶。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：仅当上传新文件时为 insert，当更新文件时为 select、insert 和 update
请参阅存储指南，了解访问控制的工作方式
如果你正在上传图像或音频，请指定适当的内容 MIME 类型。如果未指定 file_options，则 MIME 类型默认为 text/html。

参数

path
必需
字符串
文件路径，包括文件名。应采用 folder/subfolder/filename.png 的格式。在尝试上传之前，存储桶必须已经存在。
file
必需
BufferedReader | bytes | FileIO | string | Path
要存储在存储桶中的文件的主体。
file_options
必需
FileOptions

1
with open("./public/avatar1.png", "rb") as f:
2
    response = (
3
        supabase.storage
4
        .from_("avatars")
5
        .upload(
6
            file=f,
7
            path="public/avatar1.png",
8
            file_options={"cache-control": "3600", "upsert": "false"}
9
        )
10
    )

替换现有文件

用新文件替换指定路径处的现有文件。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
文件路径，包括文件名。应采用 folder/subfolder/filename.png 的格式。在尝试上传之前，存储桶必须已经存在。
file
必需
BufferedReader | bytes | FileIO | string | Path
要存储在存储桶中的文件的主体。
file_options
必需
FileOptions

1
with open("./public/avatar1.png", "rb") as f:
2
    response = (
3
        supabase.storage
4
        .from_("avatars")
5
        .update(
6
            file=f,
7
            path="public/avatar1.png",
8
            file_options={"cache-control": "3600", "upsert": "true"}
9
        )
10
    )

移动现有文件

将现有文件移动到同一存储桶中的新路径。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式

参数

from_path
必需
字符串
原始文件路径，包括当前文件名。例如 folder/image.png。
to_path
必需
字符串
新的文件路径，包括新的文件名。例如 folder/image-new.png。

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .move(
5
        "public/avatar1.png",
6
        "private/avatar2.png"
7
    )
8
)

复制现有文件

将现有文件复制到同一存储桶中的新路径。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式

参数

from_path
必需
字符串
原始文件路径，包括当前文件名。例如 folder/image.png。
to_path
必需
字符串
新的文件路径，包括新的文件名。例如 folder/image-new.png。

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .copy(
5
        "public/avatar1.png",
6
        "private/avatar2.png"
7
    )
8
)

创建签名 URL

为文件创建一个签名 URL。使用签名 URL 可以共享一个文件，持续一段时间。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
文件路径，包括文件名。例如 "folder/image.png"。
expires_in
必需
number
签名 URL 过期前的秒数。例如，对于有效期为一分钟的 URL，设置为 60。
options
可选
URLOptions

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .create_signed_url(
5
        "folder/avatar1.png",
6
        60
7
    )
8
)

创建签名 URL

创建多个签名 URL。使用签名 URL 可以共享一个文件，并在固定时间内有效。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

paths
必需
list[string]
要下载的文件路径，包括当前文件名。例如 ["folder/image.png", "folder2/image2.png"]。
expires_in
必需
number
签名 URL 过期前的秒数。例如，对于有效期为一分钟的 URL，设置为 60。
options
可选
CreateSignedURLsOptions

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .create_signed_urls(
5
        ["folder/avatar1.png", "folder/avatar2.png"],
6
        60
7
    )
8
)

创建签名上传 URL

创建一个签名上传 URL。可以使用签名上传 URL 将文件上传到存储桶，而无需进一步身份验证。它们有效期为 2 小时。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：insert
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
文件路径，包括当前文件名。例如 "folder/image.png"。
options
可选
CreateSignedUploadUrlOptions
上传 URL 创建的附加选项。

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .create_signed_upload_url("folder/avatar1.png")
5
)

上传到签名 URL

使用从 create_signed_upload_url 生成的 token 上传文件。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
文件路径，包括文件名。应采用 folder/subfolder/filename.png 的格式。在尝试上传之前，存储桶必须已经存在。
token
必需
字符串
从 create_signed_upload_url 生成的 token
file
必需
BufferedReader | bytes | FileIO | string | Path
要存储在存储桶中的文件的主体。
options
必需
UploadSignedUrlFileOptions

1
with open("./public/avatar1.png", "rb") as f:
2
    response = (
3
        supabase.storage
4
        .from_("avatars")
5
        .upload_to_signed_url(
6
            path="folder/cat.jpg",
7
            token="token-from-create_signed_upload_url",
8
            file=f,
9
        )
10
    )

检索公共 URL

一个简单的便捷函数，用于获取公共存储桶中资源的 URL。如果您不想使用此函数，可以通过将存储桶 URL 与资源的路径连接来构造公共 URL。此函数不会验证存储桶是否为公共存储桶。如果为非公共存储桶创建公共 URL，您将无法下载该资源。

存储桶需要设置为公共存储桶，可以通过 update_bucket() 或通过访问 supabase.com/dashboard 上的 Storage，单击存储桶上的溢出菜单并选择“设为公共”来实现。
所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
要生成公共 URL 的文件路径和名称。例如 folder/image.png。
options
可选
URLOptions

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .get_public_url("folder/avatar1.jpg")
5
)

下载文件

从私有存储桶下载文件。对于公共存储桶，请向从 get_public_url 返回的 URL 发送请求。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
要下载的文件的完整路径和文件名。例如 folder/image.png。
options
必需
DownloadOptions

1
with open("./myfolder/avatar1.png", "wb+") as f:
2
    response = (
3
        supabase.storage
4
        .from_("avatars")
5
        .download("folder/avatar1.png")
6
    )
7
    f.write(response)

删除存储桶中的文件

删除同一存储桶中的文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：delete 和 select
请参阅存储指南，了解访问控制的工作方式

参数

paths
必需
list[string]
要删除的文件数组，包括路径和文件名。例如 ["folder/image.png"]。

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .remove(["folder/avatar1.png"])
5
)

列出存储桶中的所有文件

列出存储桶中的所有文件。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path
可选
字符串
文件夹路径。
options
可选
SearchOptions

1
response = (
2
    supabase.storage
3
    .from_("avatars")
4
    .list(
5
        "folder",
6
        {
7
            "limit": 100,
8
            "offset": 0,
9
            "sortBy": {"column": "name", "order": "desc"},
10
        }
11
    )
12
)

分析 Bucket

本节包含处理 Analytics Buckets 的方法。

通过 supabase.storage.analytics() 命名空间访问 Analytics buckets。
Analytics buckets 用于存储和查询分析数据。

创建一个新的分析存储桶

创建一个新的 Analytics bucket。

这是一个 alpha 功能，未来可能会更改。
Analytics buckets 用于存储和查询分析数据。

参数

bucket_name
必需
字符串
要创建的分析存储桶的名称。

1
response = supabase.storage.analytics().create("analytics-bucket")

列出分析存储桶

列出所有 Analytics buckets，并可选择进行过滤和排序。

这是一个 alpha 功能，未来可能会更改。

参数

limit
可选
number
返回的最大存储桶数量。
offset
可选
number
要跳过的存储桶数量。
sort_column
可选
字符串
要排序的列。选项：id、name、created_at、updated_at。
sort_order
可选
字符串
排序顺序。选项：asc、desc。
search
可选
字符串
用于按名称过滤存储桶的搜索词。

1
response = supabase.storage.analytics().list()

删除分析存储桶

删除 Analytics bucket。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
要删除的分析存储桶的名称。

1
response = supabase.storage.analytics().delete("analytics-bucket")

向量 Bucket

本节包含处理 Vector Buckets 的方法。

创建一个向量存储桶

创建一个新的 Vector bucket。

这是一个 alpha 功能，未来可能会更改。
Vector buckets 用于存储和查询向量嵌入。

参数

bucket_name
必需
字符串
要创建的向量存储桶的名称。

1
supabase.storage.vectors().create_bucket("vectors-bucket")

删除向量存储桶

删除 Vector bucket。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
要删除的向量存储桶的名称。

1
supabase.storage.vectors().delete_bucket("vectors-bucket")

检索向量存储桶

检索 Vector bucket 的详细信息。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
要检索的向量存储桶的名称。

1
response = supabase.storage.vectors().get_bucket("vectors-bucket")

列出所有向量存储桶

列出所有 Vector buckets，并可选择进行分页。

这是一个 alpha 功能，未来可能会更改。

参数

prefix
可选
字符串
按名称前缀过滤存储桶。
max_results
可选
number
返回的最大存储桶数量。
next_token
可选
字符串
用于分页的 token。

1
response = supabase.storage.vectors().list_buckets()

创建向量索引

在向量存储桶中创建一个新的向量索引。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
要创建的索引的名称。
dimension
必需
number
此索引中向量的维度。
distance_metric
必需
字符串
要使用的距离度量。选项：cosine、euclidean。
data_type
必需
字符串
向量的数据类型。
metadata
可选
MetadataConfiguration
索引的可选元数据配置。

1
supabase.storage.vectors().from_("vectors-bucket").create_index(
2
    index_name="my-index",
3
    dimension=128,
4
    distance_metric="cosine",
5
    data_type="float32"
6
)

删除向量索引

删除向量索引。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
要删除的索引的名称。

1
supabase.storage.vectors().from_("vectors-bucket").delete_index("my-index")

检索向量索引

检索向量索引的详细信息。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
要检索的索引的名称。

1
response = supabase.storage.vectors().from_("vectors-bucket").get_index("my-index")

列出所有向量索引

列出向量存储桶中的所有索引。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
next_token
可选
字符串
用于分页的 token。
max_results
可选
number
返回的最大索引数量。
prefix
可选
字符串
按名称前缀过滤索引。

1
response = supabase.storage.vectors().from_("vectors-bucket").list_indexes()

从索引中删除向量

通过其键删除向量。

这是一个 alpha 功能，未来可能会更改。
Keys 批处理大小必须在 1 到 500 之间。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
索引的名称。
keys
必需
list[string]
要删除的向量键列表。必须包含 1 到 500 个键。

1
supabase.storage.vectors().from_("vectors-bucket").index("my-index").delete(["vector-1", "vector-2"])

从索引中检索向量

通过其键检索向量。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
索引的名称。
keys
必需
list[string]
要检索的向量键列表。
return_data
可选
bool
是否返回向量数据。默认为 true。
return_metadata
可选
bool
是否返回元数据。默认为 true。

1
response = supabase.storage.vectors().from_("vectors-bucket").index("my-index").get("vector-1")

列出索引中的向量

列出索引中的向量，并可选择进行分页。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
索引的名称。
max_results
可选
number
返回的最大向量数量。
next_token
可选
字符串
用于分页的 token。
return_data
可选
bool
是否返回向量数据。默认为 true。
return_metadata
可选
bool
是否返回元数据。默认为 true。
segment_count
可选
number
分布式查询的段数。
segment_index
可选
number
分布式查询的段索引。

1
response = supabase.storage.vectors().from_("vectors-bucket").index("my-index").list()

将向量添加到索引

将向量插入或更新到索引中。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
索引的名称。
vectors
必需
list[VectorObject]
要插入或更新的向量对象列表。

1
supabase.storage.vectors().from_("vectors-bucket").index("my-index").put([
2
    {
3
        "key": "vector-1",
4
        "data": {"float32": [0.1, 0.2, 0.3]},
5
        "metadata": {"category": "example"}
6
    }
7
])

在索引中搜索向量

使用查询向量查询向量，以查找相似的向量。

这是一个 alpha 功能，未来可能会更改。

参数

bucket_name
必需
字符串
向量存储桶的名称。
index_name
必需
字符串
索引的名称。
query_vector
必需
VectorData
用于搜索的查询向量。
topK
可选
number
要返回的结果数量。
filter
可选
VectorFilter
应用于查询的可选过滤器。
return_distance
可选
bool
是否返回距离分数。默认为 true。
return_metadata
可选
bool
是否返回元数据。默认为 true。

1
response = supabase.storage.vectors().from_("vectors-bucket").index("my-index").query(
2
    query_vector={"float32": [0.1, 0.2, 0.3]},
3
    topK=10
4
)