openref: 0.1

info:
  id: reference/supabase-py
  title: Supabase Python Client
  description: |

    Supabase Python(Community).

  definition: spec/enrichments/tsdoc_v2/combined.json
  specUrl: https://github.com/supabase/supabase/edit/master/apps/docs/spec/supabase_py_v2.yml
  slugPrefix: '/'
  libraries:
    - name: 'Python'
      id: 'py'
      version: '0.0.1'

functions:
  - id: initializing
    description: |
      You can initialize a new Supabase client using the `create_client()` method.

      The Supabase client is your entrypoint to the rest of the Supabase functionality
      and is the easiest way to interact with everything we offer within the Supabase ecosystem.

    params:
      - name: supabase_url
        isOptional: false
        type: string
        description: The unique Supabase URL which is supplied when you create a new project in your project dashboard.
      - name: supabase_key
        isOptional: false
        type: string
        description: The unique Supabase Key which is supplied when you create a new project in your project dashboard.
      - name: options
        isOptional: true
        type: ClientOptions
        description: Options to change the Auth behaviors.
        subContent:
          - name: schema
            isOptional: true
            type: string
            description: The Postgres schema which your tables belong to. Must be on the list of exposed schemas in Supabase. Defaults to 'public'.
          - name: headers
            isOptional: true
            type: dictionary
            description: Optional headers for initializing the client.
          - name: auto_refresh_token
            isOptional: true
            type: bool
            description: Whether to automatically refresh the token when it expires. Defaults to `true`.
          - name: persist_session
            isOptional: true
            type: bool
            description: Whether to persist a logged in session to storage.
          - name: storage
            isOptional: true
            type: SyncSupportedStorage
            description: A storage provider. Used to store the logged in session.
          - name: realtime
            isOptional: true
            type: string
            description: Options passed to the realtime-py instance.
          - name: postgrest_client_timeout
            isOptional: true
            type: int, float, Timeout
            description: Timeout passed to the SyncPostgrestClient instance.
          - name: storage_client_timeout
            isOptional: true
            type: int, float, Timeout
            description: Timeout passed to the SyncStorageClient instance.
          - name: flow_type
            isOptional: true
            type: AuthFlowType
            description: flow type to use for authentication.

    examples:
      - id: create-client
        name: create_client()
        code: |
          ```
          import os
          from supabase import create_client, Client

          url: str = os.environ.get("SUPABASE_URL")
          key: str = os.environ.get("SUPABASE_KEY")
          supabase: Client = create_client(url, key)
          ```
      - id: with-timeout-option
        name: With timeout option
        code: |
          ```
          import os
          from supabase import create_client, Client
          from supabase.client import ClientOptions

          url: str = os.environ.get("SUPABASE_URL")
          key: str = os.environ.get("SUPABASE_KEY")
          supabase: Client = create_client(url, key,
            options=ClientOptions(
              postgrest_client_timeout=10,
              storage_client_timeout=10,
              schema="public",
            ))
          ```

  - id: sign-up
    title: 'sign_up()'
    params:
      - name: credentials
        isOptional: false
        type: SignUpWithPasswordCredentials
        subContent:
          - name: email
            isOptional: true
            type: string
            description: One of `email` or `phone` must be provided.
          - name: phone
            isOptional: true
            type: string
            description: One of `email` or `phone` must be provided.
          - name: password
            type: string
          - name: options
            isOptional: true
            type: object
            subContent:
              - name: email_redirect_to
                isOptional: true
                type: string
                description: >
                  Only for email signups.
                  The redirect URL embedded in the email link.
                  Must be a configured redirect URL for your Supabase instance.
              - name: data
                isOptional: true
                type: object
                description: >
                  A custom data object to store additional user metadata.
              - name: captcha_token
                isOptional: true
                type: string
              - name: channel
                isOptional: true
                type: sms | whatsapp
                description: >
                  The channel to use for sending messages.
                  Only for phone signups.
    notes: |
      - By default, the user needs to verify their email address before logging in. To turn this off, disable **Confirm email** in [your project](https://supabase.com/dashboard/project/_/auth/providers).
      - **Confirm email** determines if users need to confirm their email address after signing up.
        - If **Confirm email** is enabled, a `user` is returned but `session` is null.
        - If **Confirm email** is disabled, both a `user` and a `session` are returned.
      - By default, when the user confirms their email address, they are redirected to the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls). You can modify your `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
      - If sign_up() is called for an existing confirmed user:
        - When both **Confirm email** and **Confirm phone** (even when phone provider is disabled) are enabled in [your project](/dashboard/project/_/auth/providers), an obfuscated/fake user object is returned.
        - When either **Confirm email** or **Confirm phone** (even when phone provider is disabled) is disabled, the error message, `User already registered` is returned.
      - To fetch the currently logged-in user, refer to [`get_user()`](/docs/reference/python/auth-getuser).
    examples:
      - id: signup
        name: Sign up with an email and password
        code: |
          ```python          
          response = supabase.auth.sign_up(
              credentials={"email": "hello@example.com", "password": "password"}
          )
          ```
        response: |
          ```json
          {
            "user": {
              "id": "11111111-1111-1111-1111-111111111111",
              "app_metadata": {
                "provider": "email",
                "providers": [
                  "email"
                ]
              },
              "user_metadata": {},
              "aud": "authenticated",
              "confirmation_sent_at": null,
              "recovery_sent_at": null,
              "email_change_sent_at": null,
              "new_email": null,
              "invited_at": null,
              "action_link": null,
              "email": "hello@example.com",
              "phone": "",
              "created_at": "2024-06-17T00:19:25.760110Z",
              "confirmed_at": null,
              "email_confirmed_at": "2024-06-17T00:19:25.779181Z",
              "phone_confirmed_at": null,
              "last_sign_in_at": "2024-06-17T00:19:25.785489Z",
              "role": "authenticated",
              "updated_at": "2024-06-17T00:19:25.794650Z",
              "identities": [
                {
                  "id": "11111111-1111-1111-1111-111111111111",
                  "user_id": "11111111-1111-1111-1111-111111111111",
                  "identity_data": {
                    "email": "hello@example.com",
                    "sub": "11111111-1111-1111-1111-111111111111"
                  },
                  "provider": "email",
                  "created_at": "2024-06-17T00:19:25.774522Z",
                  "last_sign_in_at": "2024-06-17T00:19:25.774498Z",
                  "updated_at": "2024-06-17T00:19:25.774522Z"
                }
              ],
              "factors": null
            },
            "session": {
              "provider_token": null,
              "provider_refresh_token": null,
              "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNzE4NTg3MTY1LCJpYXQiOjE3MTg1ODM1NjUsImlzcyI6Imh0dHA6Ly8xMjcuMC4wLjE6NTQzMjEvYXV0aC92MSIsInN1YiI6ImU0MTBkMTBmLTZlNTktNDBlNS1hMmRlLTY5NGE5MzVlNzJlZCIsImVtYWlsIjoiaGVsbG9AZXhhbXBsZS5jb20iLCJwaG9uZSI6IiIsImFwcF9tZXRhZGF0YSI6eyJwcm92aWRlciI6ImVtYWlsIiwicHJvdmlkZXJzIjpbImVtYWlsIl19LCJ1c2VyX21ldGFkYXRhIjp7fSwicm9sZSI6ImF1dGhlbnRpY2F0ZWQiLCJhYWwiOiJhYWwxIiwiYW1yIjpbeyJtZXRob2QiOiJwYXNzd29yZCIsInRpbWVzdGFtcCI6MTcxODU4MzU2NX1dLCJzZXNzaW9uX2lkIjoiMjRmOGFlMmMtYWM4Mi00NzdhLWIxMTMtZTkwNmRlNzFiMDIxIn0.5KrE1AL4koBJs5dvNQfThMV1HxV8nPP-GPU24aRL9xI",
              "refresh_token": "mNUp4-LDuYq-kNG61t-2Xw",
              "expires_in": 3600,
              "expires_at": 1718587165,
              "token_type": "bearer",
              "user": {
                "id": "11111111-1111-1111-1111-111111111111",
                "app_metadata": {
                  "provider": "email",
                  "providers": [
                    "email"
                  ]
                },
                "user_metadata": {},
                "aud": "authenticated",
                "confirmation_sent_at": null,
                "recovery_sent_at": null,
                "email_change_sent_at": null,
                "new_email": null,
                "invited_at": null,
                "action_link": null,
                "email": "hello@example.com",
                "phone": "",
                "created_at": "2024-06-17T00:19:25.760110Z",
                "confirmed_at": null,
                "email_confirmed_at": "2024-06-17T00:19:25.779181Z",
                "phone_confirmed_at": null,
                "last_sign_in_at": "2024-06-17T00:19:25.785489Z",
                "role": "authenticated",
                "updated_at": "2024-06-17T00:19:25.794650Z",
                "identities": [
                  {
                    "id": "11111111-1111-1111-1111-111111111111",
                    "user_id": "11111111-1111-1111-1111-111111111111",
                    "identity_data": {
                      "email": "hello@example.com",
                      "sub": "11111111-1111-1111-1111-111111111111"
                    },
                    "provider": "email",
                    "created_at": "2024-06-17T00:19:25.774522Z",
                    "last_sign_in_at": "2024-06-17T00:19:25.774498Z",
                    "updated_at": "2024-06-17T00:19:25.774522Z"
                  }
                ],
                "factors": null
              }
            }
          }
          ```
      - id: sign-up-phone
        name: Sign up with a phone number and password (SMS)
        isSpotlight: true
        code: |
          ```python
          response = supabase.auth.sign_up(
              credentials={
                  "phone": "123456789",
                  "password": "password",
              }
          )
          ```
      - id: sign-up-phone-whatsapp
        name: Sign up with a phone number and password (whatsapp)
        isSpotlight: true
        description: |
          The user will be sent a WhatsApp message which contains a OTP. By default, a given user can only request a OTP once every 60 seconds. Note that a user will need to have a valid WhatsApp account that is linked to Twilio in order to use this feature.
        code: |
          ```python
          response = supabase.auth.sign_up(
              credentials={
                  "phone": "123456789",
                  "password": "password",
                  "options": {"channel": "whatsapp"},
              }
          )
          ```
      - id: sign-up-with-additional-user-metadata
        name: Sign up with additional user metadata
        code: |
          ```python
          response = supabase.auth.sign_up(
              credentials={
                  "email": "hello@example.com",
                  "password": "password",
                  "options": {"data": {"first_name": "John", "age": 27}},
              }
          )
          ```
      - id: sign-up-with-redirect
        name: Sign up with a redirect URL
        description: |
          - See [redirect URLs and wildcards](/docs/guides/auth/redirect-urls) to add additional redirect URLs to your project.
        code: |
          ```python
          response = supabase.auth.sign_up(
              credentials={
                  "email": "hello1@example.com",
                  "password": "password",
                  "options": {
                      "email_redirect_to": "https://example.com/welcome",
                  },
              }
          )
          ```
  - id: sign-in-anonymously
    title: 'sign_in_anonymously()'
    params:
      - name: credentials
        isOptional: false
        type: SignInAnonymouslyCredentials
        subContent:
          - name: options
            isOptional: true
            type: object
            subContent:
              - name: data
                isOptional: true
                type: object
                description: A custom data object to store the user's metadata. This maps to the `auth.users.raw_user_meta_data` column. The `data` should be a JSON object that includes user-specific info, such as their first and last name.
              - name: captcha_token
                isOptional: true
                type: string
                description: Verification token received when the user completes the captcha on the site.
  
    notes: |
      - Returns an anonymous user
      - It is recommended to set up captcha for anonymous sign-ins to prevent abuse. You can pass in the captcha token in the `options` param.
    examples:
      - id: sign-in-anonymously
        name: Create an anonymous user
        isSpotlight: true
        code: |
          ```python
          response = supabase.auth.sign_in_anonymously(
              credentials={"options": {"captcha_token": ""}}
          )
          ```
        response: |
          ```json
          {
            "user": {
              "id": "11111111-1111-1111-1111-111111111111",
              "app_metadata": {},
              "user_metadata": {},
              "aud": "authenticated",
              "confirmation_sent_at": null,
              "recovery_sent_at": null,
              "email_change_sent_at": null,
              "new_email": null,
              "invited_at": null,
              "action_link": null,
              "email": "",
              "phone": "",
              "created_at": "2024-06-23T22:35:47.518626Z",
              "confirmed_at": null,
              "email_confirmed_at": null,
              "phone_confirmed_at": null,
              "last_sign_in_at": "2024-06-23T22:35:47.520855Z",
              "role": "authenticated",
              "updated_at": "2024-06-23T22:35:47.522241Z",
              "identities": [],
              "factors": null
            },
            "session": {
              "provider_token": null,
              "provider_refresh_token": null,
              "access_token": "<ACCESS_TOKEN>",
              "refresh_token": "<REFRESH_TOKEN>",
              "expires_in": 3600,
              "expires_at": 1719185747,
              "token_type": "bearer",
              "user": {
                "id": "11111111-1111-1111-1111-111111111111",
                "app_metadata": {},
                "user_metadata": {},
                "aud": "authenticated",
                "confirmation_sent_at": null,
                "recovery_sent_at": null,
                "email_change_sent_at": null,
                "new_email": null,
                "invited_at": null,
                "action_link": null,
                "email": "",
                "phone": "",
                "created_at": "2024-06-23T22:35:47.518626Z",
                "confirmed_at": null,
                "email_confirmed_at": null,
                "phone_confirmed_at": null,
                "last_sign_in_at": "2024-06-23T22:35:47.520855Z",
                "role": "authenticated",
                "updated_at": "2024-06-23T22:35:47.522241Z",
                "identities": [],
                "factors": null
              }
            }
          }
          ```
      - id: sign-in-anonymously-with-user-metadata
        name: Create an anonymous user with custom user metadata
        isSpotlight: false
        code: |
          ```python
          response = supabase.auth.sign_in_anonymously(
              credentials={"options": {"data": {}}}
          )
          ```
  - id: sign-in-with-password
    title: 'sign_in_with_password'
    notes: |
      - Requires either an email and password or a phone number and password.
    examples:
      - id: sign-in-with-email-and-password
        name: Sign in with email and password
        isSpotlight: true
        code: |
          ```
          data = supabase.auth.sign_in_with_password({"email": "j0@supabase.io", "password": "testsupabasenow"})
          ```
      - id: sign-in-with-phone-and-password
        name: Sign in with phone and password
        isSpotlight: false
        code: |
          ```
          data = supabase.auth.sign_in_with_password({"phone": "+1234566", password": "testsupabasenow"})
          # After receiving a SMS with a OTP.
          data = supabase.auth.verify_otp({
            "phone": '+13334445555',
            "token": '123456',
          })
          ```
  - id: sign-in-with-otp
    title: 'sign_in_with_otp'
    notes: |
      - Requires either an email or phone number.
      - This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
      - If the user doesn't exist, `sign_in_with_otp()` will signup the user instead. To restrict this behavior, you can set `should_create_user` in `SignInWithPasswordlessCredentials.options` to `false`.
      - If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
      - If you're using phone, you can configure whether you want the user to receive a OTP.
      - The magic link's destination URL is determined by the [`SITE_URL`](/docs/guides/auth/redirect-urls).
      - See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project.
      - Magic links and OTPs share the same implementation. To send users a one-time code instead of a magic link, [modify the magic link email template](https://supabase.com/dashboard/project/_/auth/templates) to include `{{ .Token }}` instead of `{{ .ConfirmationURL }}`.
    examples:
      - id: sign-in-with-email
        name: Sign in with email
        isSpotlight: true
        description: The user will be sent an email which contains either a magiclink or a OTP or both. By default, a given user can only request a OTP once every 60 seconds.
        code: |
          ```
          data = supabase.auth.sign_in_with_otp({
            "email": 'example@email.com',
            "options": {
              "email_redirect_to": 'https://example.com/welcome'
            }
          })
          ```
      - id: sign-in-with-sms-otp
        name: Sign in with SMS OTP
        isSpotlight: false
        description: The user will be sent a SMS which contains a OTP. By default, a given user can only request a OTP once every 60 seconds.
        code: |
          ```
          data = supabase.auth.sign_in_with_otp({
            "phone": '+13334445555',
          })
          ```
  - id: sign-in-with-oauth
    title: 'sign_in_with_oauth'
    notes: |
      - This method is used for signing in using a third-party provider.
      - Supabase supports many different [third-party providers](https://supabase.com/docs/guides/auth#providers).
    examples:
      - id: sign-in-using-a-third-party-provider
        name: Sign in using a third-party provider
        isSpotlight: true
        code: |
          ```
          data = supabase.auth.sign_in_with_oauth({
            "provider": 'github'
          })
          ```
      - id: sign-in-using-a-third-party-provider-with-redirect
        name: Sign in using a third-party provider with redirect
        isSpotlight: false
        description: |
          - When the third-party provider successfully authenticates the user, the provider redirects the user to the URL specified in the `redirectTo` parameter. This parameter defaults to the [`SITE_URL`](/docs/guides/auth/redirect-urls). It does not redirect the user immediately after invoking this method.
          - See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project.
        code: |
          ```
          data = supabase.auth.sign_in_with_oauth({
            "provider": 'github',
            "options": {
              "redirect_to": 'https://example.com/welcome'
            }
          })
          ```
      - id: sign-in-with-scopes
        name: Sign in with scopes
        isSpotlight: false
        description: |
          If you need additional data from an OAuth provider, you can include a space-separated list of scopes in your request to get back an OAuth provider token.
          You may also need to specify the scopes in the provider's OAuth app settings, depending on the provider. The list of scopes will be documented by the third-party provider you are using and specifying scopes will enable you to use the OAuth provider token to call additional APIs supported by the third-party provider to get more information.
        code: |
          ```
          data = supabase.auth.sign_in_with_oauth({
            "provider": 'github',
            "options": {
              "scopes": 'repo gist notifications'
            }
          })
          oauth_token = data.session.provider_token # use to access provider API
          ```
  - id: sign-out
    title: 'sign_out()'
    notes: |
      - In order to use the `signOut()` method, the user needs to be signed in first.
    examples:
      - id: sign-out
        name: Sign out
        code: |
          ```
          res = supabase.auth.sign_out()
          ```
  - id: verify-otp
    title: 'verify_otp'
    notes: |
      - The `verify_otp` method takes in different verification types. If a phone number is used, the type can either be `sms` or `phone_change`. If an email address is used, the type can be one of the following: `signup`, `magiclink`, `recovery`, `invite` or `email_change`.
      - The verification type used should be determined based on the corresponding auth method called before `verify_otp` to sign up / sign-in a user.
    examples:
      - id: verify-sms-one-time-password
        name: Verify SMS One-Time Password (OTP)
        code: |
          ```
          res = supabase.auth.verify_otp(phone, token)
          ```
  - id: auth-mfa-api
    title: 'Overview'
    notes: |
      This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the `supabase.auth.mfa` namespace.

      Currently, we only support time-based one-time password (TOTP) as the 2nd factor. We don't support recovery codes but we allow users to enroll more than 1 TOTP factor, with an upper limit of 10.

      Having a 2nd TOTP factor for recovery frees the user of the burden of having to store their recovery codes somewhere. It also reduces the attack surface since multiple recovery codes are usually generated compared to just having 1 backup TOTP factor.
  - id: mfa-enroll
    title: 'mfa.enroll()'
    notes: |
      - Currently, `totp` is the only supported `factor_type`. The returned `id` should be used to create a challenge.
      - To create a challenge, see [`mfa.challenge()`](/docs/reference/python/auth-mfa-challenge).
      - To verify a challenge, see [`mfa.verify()`](/docs/reference/python/auth-mfa-verify).
      - To create and verify a challenge in a single step, see [`mfa.challenge_and_verify()`](/docs/reference/python/auth-mfa-challengeandverify).
    examples:
      - id: enroll-totp-factor
        name: Enroll a time-based, one-time password (TOTP) factor
        isSpotlight: true
        code: |
          ```
          res = supabase.auth.mfa.enroll({
            "factor_type": "totp",
            "friendly_name": "your_friendly_name"
          })
          ```
  - id: mfa-challenge
    title: 'mfa.challenge()'
    notes: |
      - An [enrolled factor](/docs/reference/python/auth-mfa-enroll) is required before creating a challenge.
      - To verify a challenge, see [`mfa.verify()`](/docs/reference/python/auth-mfa-verify).
    examples:
      - id: create-mfa-challenge
        name: Create a challenge for a factor
        isSpotlight: true
        code: |
          ```
          res = supabase.auth.mfa.challenge({
            "factor_id": '34e770dd-9ff9-416c-87fa-43b31d7ef225'
          })
          ```
  - id: mfa-verify
    title: 'mfa.verify()'
    notes: |
      - To verify a challenge, please [create a challenge](/docs/reference/python/auth-mfa-challenge) first.
    examples:
      - id: verify-challenge
        name: Verify a challenge for a factor
        isSpotlight: true
        code: |
          ```
          res = supabase.auth.mfa.verify({
            "factor_id": '34e770dd-9ff9-416c-87fa-43b31d7ef225',
            "challenge_id": '4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15',
            "code": '123456'
          })
          ```
  - id: mfa-challenge-and-verify
    title: 'mfa.challenge_and_verify()'
    notes: |
      - An [enrolled factor](/docs/reference/python/auth-mfa-enroll) is required before invoking `challengeAndVerify()`.
      - Executes [`mfa.challenge()`](/docs/reference/python/auth-mfa-challenge) and [`mfa.verify()`](/docs/reference/python/auth-mfa-verify) in a single step.
    examples:
      - id: challenge-and-verify
        name: Create and verify a challenge for a factor
        isSpotlight: true
        code: |
          ```
          res = supabase.auth.mfa.challenge_and_verify({
            "factor_id": '34e770dd-9ff9-416c-87fa-43b31d7ef225',
            "code": '123456'
          })
          ```
  - id: mfa-unenroll
    title: 'mfa.unenroll()'
    examples:
      - id: unenroll-a-factor
        name: Unenroll a factor
        isSpotlight: true
        code: |
          ```
          res = supabase.auth.mfa.unenroll({
            "factor_id": '34e770dd-9ff9-416c-87fa-43b31d7ef225',
          })
          ```
  - id: mfa-get-authenticator-assurance-level
    title: 'mfa.get_authenticator_assurance_level()'
    notes: |
      - Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism.
      - In Supabase, having an AAL of `aal1` refers to having the 1st factor of authentication such as an email and password or OAuth sign-in while `aal2` refers to the 2nd factor of authentication such as a time-based, one-time-password (TOTP).
      - If the user has a verified factor, the `next_level` field will return `aal2`, else, it will return `aal1`.
    examples:
      - id: get-aal
        name: Get the AAL details of a session
        isSpotlight: true
        code: |
          ```
          res = supabase.auth.mfa.get_authenticator_assurance_level()
          ```
  - id: get-user
    title: 'get_user'
    notes: |
      - This method gets the user object from the current session.
      - Fetches the user object from the database instead of local session.
    examples:
      - id: get-the-logged-in-user-with-the-current-existing-session
        name: Get the logged in user with the current existing session
        isSpotlight: true
        code: |
          ```
          data = supabase.auth.get_user()
          ```
      - id: get-the-logged-in-user-with-a-custom-access-token-jwt
        name: Get the logged in user with a custom access token jwt
        isSpotlight: false
        code: |
          ```
          data = supabase.auth.get_user(jwt)
          ```

  - id: get-session
    title: 'get_session'
    examples:
      - id: get-session
        name: Get the session data
        code: |
          ```
          res = supabase.auth.get_session()
          ```

  - id: set-session
    title: 'set_session()'
    notes: |
      - `setSession()` takes in a refresh token and uses it to get a new session.
      - The refresh token can only be used once to obtain a new session.
      - [Refresh token rotation](/docs/reference/auth/config#refresh_token_rotation_enabled) is enabled by default on all projects to guard against replay attacks.
      - You can configure the [`REFRESH_TOKEN_REUSE_INTERVAL`](/docs/reference/auth/config#refresh_token_reuse_interval) which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.
    examples:
      - id: set-session
        name: Refresh the session
        description: Sets the session data from refresh_token and returns current session or an error if the refresh_token is invalid.
        code: |
          ```
          res = supabase.auth.set_session(access_token, refresh_token)
          ```
  - id: refresh-session
    title: 'refresh_session()'
    notes: |
      - This method will refresh the session whether the current one is expired or not.
    examples:
      - id: refresh-session
        name: Refresh session using the current session
        code: |
          ```
          res = supabase.auth.refresh_session()
          ```
  - id: select
    title: 'Fetch data: select()'
    notes: |
      - By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's [API settings](/dashboard/project/_/settings/api). It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use `range()` queries to paginate through your data.
      - `select()` can be combined with [Filters](/docs/reference/python/using-filters)
      - `select()` can be combined with [Modifiers](/docs/reference/python/using-modifiers)
      - `apikey` is a reserved keyword if you're using the [Supabase Platform](/docs/guides/platform) and [should be avoided as a column name](https://github.com/supabase/supabase/issues/5465).
    params:
      - name: columns
        isOptional: true
        type: string
        description: The columns to retrieve, defaults to `*`.
      - name: count
        isOptional: true
        type: CountMethod
        description: The property to use to get the count of rows returned.
    examples:
      - id: getting-your-data
        name: Getting your data
        code: |
          ```python
          response = supabase.table("countries").select("*").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Afghanistan"
              },
              {
                "id": 2,
                "name": "Albania"
              },
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
      - id: selecting-specific-columns
        name: Selecting specific columns
        code: |
          ```
          response = supabase.table("countries").select("name").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Afghanistan"
              },
              {
                "name": "Albania"
              },
              {
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
      - id: query-referenced-tables
        name: Query referenced tables
        description: |
          If your database has foreign key relationships, you can query related tables too.
        code: |
          ```python
          response = supabase.table("countries").select("name, cities(name)").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Germany",
                "cities": [
                  {
                    "name": "Munich"
                  }
                ]
              },
              {
                "name": "Indonesia",
                "cities": [
                  {
                    "name": "Bali"
                  }
                ]
              }
            ],
            "count": null
          }
          ```
      - id: query-referenced-tables-through-a-join-table
        name: Query referenced tables through a join table
        code: |
          ```python
          response = supabase.table("users").select("name, teams(name)").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text
              );
            create table
              teams (
                id int8 primary key,
                name text
              );
            -- join table
            create table
              users_teams (
                user_id int8 not null references users,
                team_id int8 not null references teams,
                -- both foreign keys must be part of a composite primary key
                primary key (user_id, team_id)
              );

            insert into
              users (id, name)
            values
              (1, 'Kiran'),
              (2, 'Evan');
            insert into
              teams (id, name)
            values
              (1, 'Green'),
              (2, 'Blue');
            insert into
              users_teams (user_id, team_id)
            values
              (1, 1),
              (1, 2),
              (2, 2);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Kiran",
                "teams": [
                  {
                    "name": "Green"
                  },
                  {
                    "name": "Blue"
                  }
                ]
              },
              {
                "name": "Evan",
                "teams": [
                  {
                    "name": "Blue"
                  }
                ]
              }
            ],
            "count": null
          }
          ```
        description: |
          If you're in a situation where your tables are **NOT** directly
          related, but instead are joined by a _join table_, you can still use
          the `select()` method to query the related data. The join table needs
          to have the foreign keys as part of its composite primary key.
        hideCodeBlock: true
      - id: query-the-same-referenced-table-multiple-times
        name: Query the same referenced table multiple times
        code: |
          ```python
          response = (
              supabase.table("messages")
              .select("content,from:sender_id(name),to:receiver_id(name)")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
             create table
             users (id int8 primary key, name text);

             create table
               messages (
                 sender_id int8 not null references users,
                 receiver_id int8 not null references users,
                 content text
               );

             insert into
               users (id, name)
             values
               (1, 'Kiran'),
               (2, 'Evan');

             insert into
               messages (sender_id, receiver_id, content)
             values
               (1, 2, '👋');
             ```
        response: |
          ```json
          {
            "data": [
              {
                "content": "👋",
                "from": {
                  "name": "Kiran"
                },
                "to": {
                  "name": "Evan"
                }
              }
            ],
            "count": null
          }
          ```
        description: |
          If you need to query the same referenced table twice, use the name of the
          joined column to identify which join to use. You can also give each
          column an alias.
        hideCodeBlock: true
      - id: filtering-through-referenced-tables
        name: Filtering through referenced tables
        code: |
          ```python
          response = (
              supabase.table("cities")
              .select("name, countries(*)")
              .eq("countries.name", "Estonia")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Bali",
                "countries": null
              },
              {
                "name": "Munich",
                "countries": null
              }
            ],
            "count": null
          }
          ```
        description: |
          If the filter on a referenced table's column is not satisfied, the referenced
          table returns `[]` or `null` but the parent table is not filtered out.
          If you want to filter out the parent table rows, use the `!inner` hint
        hideCodeBlock: true
      - id: querying-referenced-table-with-count
        name: Querying referenced table with count
        code: |
          ```python
          response = supabase.table("countries").select("*, cities(count)").execute()
          ```
        data:
          sql: |
            ```sql
            create table countries (
              "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null,
              "name" text
            );

            create table cities (
              "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null,
              "name" text,
              "country_id" "uuid" references public.countries on delete cascade
            );

            with country as (
              insert into countries (name)
              values ('united kingdom') returning id
            )
            insert into cities (name, country_id) values
            ('London', (select id from country)),
            ('Manchester', (select id from country)),
            ('Liverpool', (select id from country)),
            ('Bristol', (select id from country));
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": "c31e7151-5a6f-453c-915b-caf31ec9a0a0",
                "name": "united kingdom",
                "cities": [
                  {
                    "count": 4
                  }
                ]
              }
            ],
            "count": null
          }
          ```
        description: |
          You can get the number of rows in a related table by using the
          **count** property.
        hideCodeBlock: true
      - id: querying-with-count-option
        name: Querying with count option
        code: |
          ```python
          response = supabase.table("countries").select("*", count="exact").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Afghanistan"
              },
              {
                "id": 2,
                "name": "Albania"
              },
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": 3
          }
          ```
        description: |
          You can get the number of rows by using the
          *count* parameter in the select query.
        hideCodeBlock: true
      - id: querying-json-data
        name: Querying JSON data
        code: |
          ```python
          response = supabase.table("users").select("id, name, address->city").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                address jsonb
              );

            insert into
              users (id, name, address)
            values
              (1, 'Avdotya', '{"city":"Saint Petersburg"}');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Avdotya",
                "city": "Saint Petersburg"
              }
            ],
            "count": null
          }
          ```
        description: |
          You can select and filter data inside of
          [JSON](/docs/guides/database/json) columns. Postgres offers some
          [operators](/docs/guides/database/json#query-the-jsonb-data) for
          querying JSON data.
        hideCodeBlock: true
      - id: querying-referenced-table-with-inner-join
        name: Querying referenced table with inner join
        code: |
          ```python
          response = (
              supabase.table("cities")
              .select("name, countries!inner(name)")
              .eq("countries.name", "Indonesia")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Bali",
                "countries": {
                  "name": "Indonesia"
                }
              }
            ],
            "count": null
          }
          ```
        description: |
          If you don't want to return the referenced table contents, you can leave the parenthesis empty.
          Like `.select('name, countries!inner()')`.
        hideCodeBlock: true
      - id: switching-schemas-per-query
        name: Switching schemas per query
        code: |
          ```python
          response = supabase.schema("myschema").table("mytable").select("*").execute()
          ```
        data:
          sql: |
            ```sql
            create schema myschema;

            create table myschema.mytable (
              id uuid primary key default gen_random_uuid(),
              data text
            );

            insert into myschema.mytable (data) values ('mydata');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": "b1a8c0b5-bdf0-46f1-95a5-f0fb9cb2f410",
                "data": "mydata"
              }
            ],
            "count": null
          }
          ```
        description: |
          In addition to setting the schema during initialization, you can also switch schemas on a per-query basis.
          Make sure you've set up your [database privileges and API settings](/docs/guides/api/using-custom-schemas).
        hideCodeBlock: true

  - id: insert
    title: 'Create data: insert()'
    params:
      - name: json
        isOptional: false
        type: dict, list
        description: The values to insert. Pass an dict to insert a single row or an list to insert multiple rows.
      - name: count
        isOptional: true
        type: CountMethod
        description: The property to use to get the count of rows returned.
      - name: returning
        isOptional: true
        type: ReturnMethod
        description:  Either 'minimal' or 'representation'. Defaults to 'representation'.
      - name: default_to_null
        isOptional: true
        type: bool
        description:  Make missing fields default to `null`. Otherwise, use the default value for the column. Only applies for bulk inserts.
    examples:
      - id: create-a-record
        name: Create a record
        code: |
          ```python
          response = (
              supabase.table("countries")
              .insert({"id": 1, "name": "Denmark"})
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Denmark"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: bulk-create
        name: Bulk create
        code: |
          ```python
          try:
            response = supabase.table("countries")
              .insert([
                { "id": 1, "name": "Nepal" },
                { "id": 1, "name": "Vietnam" },
              ])
              .execute()
            return response
          except Exception as exception:
            return exception
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            ```
        response: |
          ```json
          {
            "_raw_error": {
              "code": "23505",
              "details": "Key (id)=(1) already exists.",
              "hint": null,
              "message": "duplicate key value violates unique constraint \"countries_pkey\""
            },
            "message": "duplicate key value violates unique constraint \"countries_pkey\"",
            "code": "23505",
            "hint": null,
            "details": "Key (id)=(1) already exists."
          }
          ```
        description: |
          A bulk create operation is handled in a single transaction.
          If any of the inserts fail, none of the rows are inserted.
        hideCodeBlock: true
  - id: update
    title: 'Modify data: update()'
    notes: |
      - `update()` should always be combined with [Filters](/docs/reference/python/using-filters) to target the item(s) you wish to update.
    params:
      - name: json
        isOptional: false
        type: dict, list
        description: The values to insert. Pass an dict to insert a single row or an list to insert multiple rows.
      - name: count
        isOptional: true
        type: CountMethod
        description: The property to use to get the count of rows returned.
      - name: returning
        isOptional: true
        type: ReturnMethod
        description:  Either 'minimal' or 'representation'. Defaults to 'representation'.
      - name: ignore_duplicates
        isOptional: true
        type: bool
        description:  Whether duplicate rows should be ignored.
      - name: on_conflict
        isOptional: true
        type: bool
        description:  Specified columns to be made to work with UNIQUE constraint.
      - name: default_to_null
        isOptional: true
        type: bool
        description: |
          Make missing fields default to `null`. Otherwise, use the default value for the column. This only applies when inserting new rows, not when merging with existing rows under `ignore_duplicates: false`. This also only applies when doing bulk upserts.
    examples:
      - id: updating-your-data
        name: Updating your data
        code: |
          ```python
          response = (
              supabase.table("countries")
              .update({"name": "Australia"})
              .eq("id", 1)
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Denmark');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Australia"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: updating-json-data
        name: Updating JSON data
        code: |
          ```python
          response = (
              supabase.table("users")
              .update({"address": {"street": "Melrose Place", "postcode": 90210}})
              .eq("address->postcode", 90210)
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                address jsonb
              );

            insert into
              users (id, name, address)
            values
              (1, 'Michael', '{ "postcode": 90210 }');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Michael",
                "address": {
                  "street": "Melrose Place",
                  "postcode": 90210
                }
              }
            ],
            "count": null
          }
          ```
        description: |
          Postgres offers some [operators](/docs/guides/database/json#query-the-jsonb-data) for working with JSON data. Currently, it is only possible to update the entire JSON document.
        hideCodeBlock: true
  - id: upsert
    title: 'Upsert data: upsert()'
    notes: |
      - Primary keys must be included in the `values` dict to use upsert.
    params:
      - name: json
        isOptional: false
        type: dict, list
        description: The values to insert. Pass an dict to insert a single row or an list to insert multiple rows.
      - name: count
        isOptional: true
        type: CountMethod
        description: The property to use to get the count of rows returned.
      - name: returning
        isOptional: true
        type: ReturnMethod
        description:  Either 'minimal' or 'representation'. Defaults to 'representation'.
      - name: ignore_duplicates
        isOptional: true
        type: bool
        description:  Whether duplicate rows should be ignored.
      - name: on_conflict
        isOptional: true
        type: bool
        description:  Specified columns to be made to work with UNIQUE constraint.
      - name: default_to_null
        isOptional: true
        type: bool
        description:  Make missing fields default to `null`. Otherwise, use the default value for the column. Only applies for bulk inserts.
    examples:
      - id: upsert-your-data
        name: Upsert your data
        code: |
          ```python
          response = (
              supabase.table("countries")
              .upsert({"id": 1, "name": "Australia"})
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Australia"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: bulk-upsert-your-data
        name: Bulk Upsert your data
        code: |
          ```python
          response = (
              supabase.table("countries")
              .upsert([{"id": 1, "name": "Albania"}, {"id": 2, "name": "Algeria"}])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Albania"
              },
              {
                "id": 2,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
      - id: upserting-into-tables-with-constraints
        name: Upserting into tables with constraints
        code: |
          ```python
          response = (
              supabase.table("users")
              .upsert(
                  {"id": 42, "handle": "saoirse", "display_name": "Saoirse"},
                  on_conflict="handle",
              )
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 generated by default as identity primary key,
                handle text not null unique,
                display_name text
              );

            insert into
              users (id, handle, display_name)
            values
              (1, 'saoirse', null);
            ```
        response: |
          ```json
          {
            "_raw_error": {
              "code": "23505",
              "details": "Key (handle)=(saoirse) already exists.",
              "hint": null,
              "message": "duplicate key value violates unique constraint \"users_handle_key\""
            },
            "message": "duplicate key value violates unique constraint \"users_handle_key\"",
            "code": "23505",
            "hint": null,
            "details": "Key (handle)=(saoirse) already exists."
          }
          ```
        description: |
          In the following query, `upsert()` implicitly uses the `id`(primary key) column to determine conflicts. If there is no existing row with the same `id`, `upsert()` inserts a new row, which will fail in this case as there is already a row with `handle` `"saoirse"`.
          Using the `on_conflict` option, you can instruct `upsert()` to use another column with a unique constraint to determine conflicts.
        hideCodeBlock: true

  - id: delete
    title: 'Delete data: delete()'
    notes: |
      - `delete()` should always be combined with [filters](/docs/reference/python/using-filters) to target the item(s) you wish to delete.
      - If you use `delete()` with filters and you have
        [RLS](/docs/learn/auth-deep-dive/auth-row-level-security) enabled, only
        rows visible through `SELECT` policies are deleted. Note that by default
        no rows are visible, so you need at least one `SELECT`/`ALL` policy that
        makes the rows visible.
      - When using `delete().in_()`, specify an array of values to target multiple rows with a single query. This is particularly useful for batch deleting entries that share common criteria, such as deleting users by their IDs. Ensure that the array you provide accurately represents all records you intend to delete to avoid unintended data removal.
    params:
      - name: count
        isOptional: true
        type: CountMethod
        description: The property to use to get the count of rows returned.
      - name: returning
        isOptional: true
        type: ReturnMethod
        description:  Either 'minimal' or 'representation'. Defaults to 'representation'.
    examples:
      - id: delete-records
        name: Delete records
        code: |
          ```python
          response = supabase.table('countries').delete().eq('id', 1).execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Spain');
            ```
        response: |
          ```
          {
            "data": [
              {
                "id": 1,
                "name": "Spain"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: delete-multiple-records
        name: Delete multiple records
        code: |
          ```python
          response = supabase.table("countries").delete().in_("id", [1, 2, 3]).execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Spain'), (2, 'France'), (3, 'Germany');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Spain"
              },
              {
                "id": 2,
                "name": "France"
              },
              {
                "id": 3,
                "name": "Germany"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: false
        isSpotlight: false

  - id: rpc
    title: 'Postgres functions: rpc()'
    description: |
      You can call Postgres functions as _Remote Procedure Calls_, logic in your database that you can execute from anywhere.
      Functions are useful when the logic rarely changes—like for password resets and updates.

      ```sql
      create or replace function hello_world() returns text as $$
        select 'Hello world';
      $$ language sql;
      ```
    params:
      - name: fn
        isOptional: false
        type: callable
        description: The stored procedure call to be executed.
      - name: params
        isOptional: true
        type: dict of any
        description:  Parameters passed into the stored procedure call.
      - name: get
        isOptional: true
        type: dict of any
        description:  When set to `true`, `data` will not be returned. Useful if you only need the count.
      - name: head
        isOptional: true
        type: dict of any
        description:  When set to `true`, the function will be called with read-only access mode.
      - name: count
        isOptional: true
        type: CountMethod
        description: |
          Count algorithm to use to count rows returned by the function. Only applicable for [set-returning functions](https://www.postgresql.org/docs/current/functions-srf.html). `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the hood. `"planned"`: Approximated but fast count algorithm. Uses the Postgres statistics under the hood. `"estimated"`: Uses exact count for low numbers and planned count for high numbers.
    examples:
      - id: call-a-postgres-function-without-arguments
        name: Call a Postgres function without arguments
        code: |
          ```python
          response = supabase.rpc("hello_world").execute()
          ```
        data:
          sql: |
            ```sql
            create function hello_world() returns text as $$
              select 'Hello world';
            $$ language sql;
            ```
        response: |
          ```json
          {
            "data": "Hello world",
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: call-a-postgres-function-with-arguments
        name: Call a Postgres function with arguments
        code: |
          ```python
          response = supabase.rpc("echo", { "say": "👋" }).execute()
          ```
        data:
          sql: |
            ```sql
            create function echo(say text) returns text as $$
              select say;
            $$ language sql;
            ```
        response: |
          ```json
            {
              "data": "👋",
              "count": null
            }
            ```
        hideCodeBlock: true
      - id: bulk-processing
        name: Bulk processing
        code: |
          ```python
          response = supabase.rpc("add_one_each", {"arr": [1, 2, 3]}).execute()
          ```
        data:
          sql: |
            ```sql
            create function add_one_each(arr int[]) returns int[] as $$
              select array_agg(n + 1) from unnest(arr) as n;
            $$ language sql;
            ```
        response: |
          ```json
          {
            "data": [
              2,
              3,
              4
            ],
            "count": null
          }
          ```
        description: |
          You can process large payloads by passing in an array as an argument.
        hideCodeBlock: true
      - id: call-a-postgres-function-with-filters
        name: Call a Postgres function with filters
        code: |
          ```python
          response = supabase.rpc("list_stored_countries").eq("id", 1).single().execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'France'),
              (2, 'United Kingdom');

            create function list_stored_countries() returns setof countries as $$
              select * from countries;
            $$ language sql;
            ```
        response: |
          ```json
          {
            "data": {
              "id": 1,
              "name": "France"
            },
            "count": null
          }
          ```
        description: |
          Postgres functions that return tables can also be combined with [Filters](/docs/reference/javascript/using-filters) and [Modifiers](/docs/reference/javascript/using-modifiers).
        hideCodeBlock: true
      - id: call-a-read-only-postgres-function
        name: Call a read-only Postgres function
        code: |
          ```python
          response = supabase.rpc('hello_world', get=True).execute()
          ```
        data:
          sql: |
            ```sql
            create function hello_world() returns text as $$
              select 'Hello world';
            $$ language sql;
            ```
        response: |
          ```json
          {
            "data": "Hello world",
            "count": null
          }
          ```
        hideCodeBlock: true


  - id: using-filters
    title: Using Filters
    description: |
      Filters allow you to only return rows that match certain conditions.

      Filters can be used on `select()`, `update()`, `upsert()`, and `delete()` queries.

      If a Postgres function returns a table response, you can also apply filters.
    examples:
      - id: applying-filters
        name: Applying Filters
        description: |
          Filters must be applied after any of `select()`, `update()`, `upsert()`,
          `delete()`, and `rpc()` and before
          [modifiers](/docs/reference/python/using-modifiers).
        code: |
          ```python
          # Correct
          response = (
              supabase.table("cities")
              .select("name, country_id")
              .eq("name", "Bali")
              .execute()
          )

          # Incorrect
          response = (
              supabase.table("cities")
              .eq("name", "Bali")
              .select("name, country_id")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
      - id: chaining-filters
        name: Chaining
        description: |
          Filters can be chained together to produce advanced queries. For example,
          to query cities with population between 1,000 and 10,000.
        code: |
          ```python
          response = (
              supabase.table("cities")
              .select("name, country_id")
              .gte("population", 1000)
              .lt("population", 10000)
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text,
                population int8
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name, population)
            values
              (1, 2, 'Bali', 9980),
              (2, 1, 'Munich', 250000);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Bali",
                "country_id": 2
              }
            ],
            "count": null
          }
          ```
      - id: conditional-chaining
        name: Conditional chaining
        description: |
          Filters can be built up one step at a time and then executed.
        code: |
          ```python
          filterByName = None
          filterPopLow = 1000
          filterPopHigh = 10000

          query = supabase.table("cities").select("name, country_id")

          if filterByName:
              query = query.eq("name", filterByName)

          if filterPopLow:
              query = query.gte("population", filterPopLow)

          if filterPopHigh:
              query = query.lt("population", filterPopHigh)

          response = query.execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text,
                population int8
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name, population)
            values
              (1, 2, 'Bali', 9980),
              (2, 1, 'Munich', 250000);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Bali",
                "country_id": 2
              }
            ],
            "count": null
          }
          ```
      - id: filter-by-value-within-json-column
        name: Filter by values within JSON column
        code: |
          ```python
          response = (
              supabase.table("users")
              .select("*")
              .eq("address->postcode", 90210)
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                address jsonb
              );

            insert into
              users (id, name, address)
            values
              (1, 'Michael', '{ "postcode": 90210 }'),
              (2, 'Jane', null);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Michael",
                "address": {
                  "postcode": 90210
                }
              }
            ],
            "count": null
          }
          ```
      - id: filter-foreign-tables
        name: Filter Foreign Tables
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name, cities!inner(name)")
              .eq("cities.name", "Bali")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Indonesia",
                "cities": [
                  {
                    "name": "Bali"
                  }
                ]
              }
            ],
            "count": null
          }
          ```
        description: |
          You can filter on foreign tables in your `select()` query using dot
          notation.

  - id: eq
    title: eq()
    description: |
      Match only rows where `column` is equal to `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: value
        isOptional: false
        type: any
        description: The value to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").eq("name", "Albania").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: neq
    title: neq()
    description: |
      Match only rows where `column` is not equal to `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: value
        isOptional: false
        type: any
        description: The value to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").neq("name", "Albania").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Afghanistan"
              },
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: gt
    title: gt()
    description: |
      Match only rows where `column` is greather than `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: value
        isOptional: false
        type: any
        description: The value to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").gt("id", 2).execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
        description: |
          When using [reserved words](https://www.postgresql.org/docs/current/sql-keywords-appendix.html) for column names you need
          to add double quotes e.g. `.gt('"order"', 2)`
  - id: gte
    title: gte()
    description: |
      Match only rows where `column` is greater than or equal to `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: value
        isOptional: false
        type: any
        description: The value to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").gte("id", 2).execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": "Albania"
              },
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: lt
    title: lt()
    description: |
      Match only rows where `column` is less than `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: value
        isOptional: false
        type: any
        description: The value to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").lt("id", 2).execute()
          ```
        data:
          sql: |
            ```sql
            create table
            countries (id int8 primary key, name text);

            insert into
            countries (id, name)
            values
            (1, 'Afghanistan'),
            (2, 'Albania'),
            (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Afghanistan"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: lte
    title: lte()
    description: |
      Match only rows where `column` is less than or equal to `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: value
        isOptional: false
        type: any
        description: The value to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").lte("id", 2).execute()
          ```
        data:
          sql: |
            ```sql
            create table
            countries (id int8 primary key, name text);

            insert into
            countries (id, name)
            values
            (1, 'Afghanistan'),
            (2, 'Albania'),
            (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Afghanistan"
              },
              {
                "id": 2,
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: like
    title: like()
    description: |
      Match only rows where `column` matches `pattern` case-sensitively.
    params:
      - name: column
        isOptional: false
        type: string
        description: The name of the column to apply a filter on
      - name: pattern
        isOptional: false
        type: string
        description: The pattern to match by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").like("name", "%Alba%").execute()
          ```
        data:
          sql: |
            ```sql
            create table
            countries (id int8 primary key, name text);

            insert into
            countries (id, name)
            values
            (1, 'Afghanistan'),
            (2, 'Albania'),
            (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: ilike
    title: ilike()
    description: |
      Match only rows where `column` matches `pattern` case-insensitively.
    params:
      - name: column
        isOptional: false
        type: string
        description: The name of the column to apply a filter on
      - name: pattern
        isOptional: false
        type: string
        description: The pattern to match by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("*").ilike("name", "%alba%").execute()
          ```
        data:
          sql: |
            ```sql
            create table
            countries (id int8 primary key, name text);

            insert into
            countries (id, name)
            values
            (1, 'Afghanistan'),
            (2, 'Albania'),
            (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: is
    title: is_()
    description: |
      Match only rows where `column` IS `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The name of the column to apply a filter on
      - name: value
        isOptional: false
        type: null | boolean
        description: The value to match by
    examples:
      - id: checking-nullness
        name: Checking for nullness, True or False
        code: |
          ```python
          response = supabase.table("countries").select("*").is_("name", "null").execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, null);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": null
              }
            ],
            "count": null
          }
          ```
        description: |
          Using the `eq()` filter doesn't work when filtering for `null`. Instead, you need to use `is_()`.

          To query for null values in python use the string 'null' instead of the python `None` value.

          Note that `is` is a reserved word in Python, so the underscore is added to avoid a syntax error.
        hideCodeBlock: true
        isSpotlight: true
  - id: in
    title: in_()
    description: |
      Match only rows where `column` is included in the `values` array.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: values
        isOptional: false
        type: array
        description: The values to filter by
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .in_("name", ["Albania", "Algeria"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
            countries (id int8 primary key, name text);

            insert into
            countries (id, name)
            values
            (1, 'Afghanistan'),
            (2, 'Albania'),
            (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": "Albania"
              },
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: contains
    title: contains()
    description: |
      Only relevant for jsonb, array, and range columns. Match only rows where `column` contains every element appearing in `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: values
        isOptional: false
        type: object
        description: The jsonb, array, or range value to filter with
    examples:
      - id: on-array-columns
        name: On array columns
        code: |
          ```python
          response = (
              supabase.table("issues")
              .select("*")
              .contains("tags", ["is:open", "priority:low"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                tags text[]
              );
            insert into
              issues (id, title, tags)
            values
              (1, 'Cache invalidation is not working', array['is:open', 'severity:high', 'priority:low']),
              (2, 'Use better names', array['is:open', 'severity:low', 'priority:medium']);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "title": "Cache invalidation is not working",
                "tags": [
                  "is:open",
                  "severity:high",
                  "priority:low"
                ]
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-range-columns
        name: On range columns
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .contains("during", "[2000-01-01 13:00, 2000-01-01 13:30)")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "room_name": "Emerald",
                "during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
              }
            ],
            "count": null
          }
          ```
        description: |
          Postgres supports a number of [range
          types](https://www.postgresql.org/docs/current/rangetypes.html). You
          can filter on range columns using the string representation of range
          values.
        hideCodeBlock: true
      - id: on-jsonb-columns
        name: On `jsonb` columns
        code: |
          ```python
          response = (
              supabase.table("users")
              .select("*")
              .contains("address", {"postcode": 90210})
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                address jsonb
              );

            insert into
              users (id, name, address)
            values
              (1, 'Michael', '{ "postcode": 90210, "street": "Melrose Place" }'),
              (2, 'Jane', '{}');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Michael",
                "address": {
                  "street": "Melrose Place",
                  "postcode": 90210
                }
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
  - id: contained-by
    title: contained_by()
    description: |
      Only relevant for jsonb, array, and range columns. Match only rows where every element appearing in `column` is contained by `value`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The jsonb, array, or range column to filter on
      - name: value
        isOptional: false
        type: object
        description: The jsonb, array, or range value to filter with
    examples:
      - id: on-array-columns
        name: On array columns
        code: |
          ```python
          response = (
              supabase.table("classes")
              .select("name")
              .contained_by("days", ["monday", "tuesday", "wednesday", "friday"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              classes (
                  id int8 primary key,
                  name text,
                  days text[]
              );

            insert into
              classes (id, name, days)
            values
              (1, 'Chemistry', array['monday', 'friday']),
              (2, 'History', array['monday', 'wednesday', 'thursday']);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Chemistry"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-range-columns
        name: On range columns
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .contained_by("during", "[2000-01-01 00:00, 2000-01-01 23:59)")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "room_name": "Emerald",
                "during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
              }
            ],
            "count": null
          }
          ```
        description: |
          Postgres supports a number of [range
          types](https://www.postgresql.org/docs/current/rangetypes.html). You
          can filter on range columns using the string representation of range
          values.
        hideCodeBlock: true
      - id: on-jsonb-columns
        name: On `jsonb` columns
        code: |
          ```python
          response = (
              supabase.table("users")
              .select("name")
              .contained_by("address", {})
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                address jsonb
              );

            insert into
              users (id, name, address)
            values
              (1, 'Michael', '{ "postcode": 90210, "street": "Melrose Place" }'),
              (2, 'Jane', '{}');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Jane"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
  - id: range-gt
    title: range_gt()
    description: |
      Only relevant for range columns. Match only rows where every element in `column` is greater than any element in `range`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The range column to filter on
      - name: range
        isOptional: false
        type: array
        description: The range to filter with
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .range_gt("during", ["2000-01-02 08:00", "2000-01-02 09:00"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
            {
              "data": [
                {
                  "id": 2,
                  "room_name": "Topaz",
                  "during": "[\"2000-01-02 09:00:00\",\"2000-01-02 10:00:00\")"
                }
              ],
              "count": null
            }
            ```
        description: |
          Postgres supports a number of [range types](https://www.postgresql.org/docs/current/rangetypes.html). You can filter on range columns using the string representation of range values.
        hideCodeBlock: true
        isSpotlight: true
  - id: range-gte
    title: range_gte()
    description: |
      Only relevant for range columns. Match only rows where every element in `column` is either contained in `range` or greater than any element in `range`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The range column to filter on
      - name: range
        isOptional: false
        type: string
        description: The range to filter with
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .range_gte("during", ["2000-01-02 08:30", "2000-01-02 09:30"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "room_name": "Topaz",
                "during": "[\"2000-01-02 09:00:00\",\"2000-01-02 10:00:00\")"
              }
            ],
            "count": null
          }  
          ```
        description: |
          Postgres supports a number of [range types](https://www.postgresql.org/docs/current/rangetypes.html). You can filter on range columns using the string representation of range values.
        hideCodeBlock: true
        isSpotlight: true
  - id: range-lt
    title: range_lt()
    description: |
      Only relevant for range columns. Match only rows where every element in `column` is less than any element in `range`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The range column to filter on
      - name: range
        isOptional: false
        type: array
        description: The range to filter with
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .range_lt("during", ["2000-01-01 15:00", "2000-01-01 16:00"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "room_name": "Emerald",
                "during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
              }
            ],
            "count": null
          }
          ```
        description: |
          Postgres supports a number of [range types](https://www.postgresql.org/docs/current/rangetypes.html). You can filter on range columns using the string representation of range values.
        hideCodeBlock: true
        isSpotlight: true
  - id: range-lte
    title: range_lte()
    description: |
      Only relevant for range columns. Match only rows where every element in `column` is less than any element in `range`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The range column to filter on
      - name: range
        isOptional: false
        type: array
        description: The range to filter with
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .range_lte("during", ["2000-01-01 14:00", "2000-01-01 16:00"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
            {
              "data": [
                {
                  "id": 1,
                  "room_name": "Emerald",
                  "during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
                }
              ],
              "count": null
            }
          ```
        description: |
          Postgres supports a number of [range types](https://www.postgresql.org/docs/current/rangetypes.html). You can filter on range columns using the string representation of range values.
        hideCodeBlock: true
        isSpotlight: true
  
  - id: range-adjacent
    title: range_adjacent()
    description: |
      Only relevant for range columns. Match only rows where `column` is mutually exclusive to `range` and there can be no element between the two ranges.
    params:
      - name: column
        isOptional: false
        type: string
        description: The range column to filter on
      - name: range
        isOptional: false
        type: array
        description: The range to filter with
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .range_adjacent("during", ["2000-01-01 12:00", "2000-01-01 13:00"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "room_name": "Emerald",
                "during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
              }
            ],
            "count": null
          }
          ```
        description: |
          Postgres supports a number of [range types](https://www.postgresql.org/docs/current/rangetypes.html). You can filter on range columns using the string representation of range values.
        hideCodeBlock: true
        isSpotlight: true

  - id: overlaps
    title: overlaps()
    description: |
      Only relevant for array and range columns. Match only rows where `column` and `value` have an element in common.
    params:
      - name: column
        isOptional: false
        type: string
        description: The array or range column to filter on
      - name: value
        isOptional: false
        type: Iterable[Any]
        description: The array or range value to filter with
    examples:
      - id: on-array-columns
        name: On array columns
        code: |
          ```python
          response = (
              supabase.table("issues")
              .select("title")
              .overlaps("tags", ["is:closed", "severity:high"])
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              issues (
                id int8 primary key,
                title text,
                tags text[]
              );

            insert into
              issues (id, title, tags)
            values
              (1, 'Cache invalidation is not working', array['is:open', 'severity:high', 'priority:low']),
              (2, 'Use better names', array['is:open', 'severity:low', 'priority:medium']);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "title": "Cache invalidation is not working"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-range-columns
        name: On range columns
        code: |
          ```python
          response = (
              supabase.table("reservations")
              .select("*")
              .overlaps("during", "[2000-01-01 12:45, 2000-01-01 13:15)")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              reservations (
                id int8 primary key,
                room_name text,
                during tsrange
              );

            insert into
              reservations (id, room_name, during)
            values
              (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),
              (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "room_name": "Emerald",
                "during": "[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")"
              }
            ],
            "status": 200,
            "statusText": "OK"
          }
          ```
        description: |
          Postgres supports a number of [range types](https://www.postgresql.org/docs/current/rangetypes.html). You can filter on range columns using the string representation of range values.
        hideCodeBlock: true

  - id: text-search
    title: text_search()
    description: |
      Only relevant for text and tsvector columns. Match only rows where `column` matches the query string in `query`.

    params:
      - name: column
        isOptional: false
        type: string
        description: The text or tsvector column to filter on
      - name: query
        isOptional: false
        type: string
        description: The query text to match with
      - name: options
        isOptional: true
        type: object
        description: Named parameters
        subContent:
          - name: type
            isOptional: true
            type: '"plain" | "phrase" | "websearch"'
            description: Change how the `query` text is interpreted
          - name: config
            isOptional: true
            type: string
            description: The text search configuration to use
    notes: |
      - For more information, see [Postgres full text search](/docs/guides/database/full-text-search).
    examples:
      - id: text-search
        name: Text search
        code: |
          ```python
          response = (
              supabase.table("texts")
              .select("content")
              .text_search("content", "'eggs' & 'ham'", options={"config": "english"})
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table texts (
              id      bigint
                      primary key
                      generated always as identity,
              content text
            );

            insert into texts (content) values
                ('Four score and seven years ago'),
                ('The road goes ever on and on'),
                ('Green eggs and ham')
            ;
            ```
        response: |
          ```json
          {
            "data": [
              {
                "content": "Green eggs and ham"
              }
            ],
            "count": null
          }
          ```
      - id: basic-normalization
        name: Basic normalization
        description: Uses PostgreSQL's `plainto_tsquery` function.
        code: |
          ```python
          response = (
              supabase.table("quotes")
              .select("catchphrase")
              .text_search(
                  "catchphrase",
                  "'fat' & 'cat'",
                  options={"type": "plain", "config": "english"},
              )
              .execute()
          )
          ```
      - id: full-normalization
        name: Full normalization
        description: Uses PostgreSQL's `phraseto_tsquery` function.
        code: |
          ```python
          response = (
              supabase.table("quotes")
              .select("catchphrase")
              .text_search(
                  "catchphrase",
                  "'fat' & 'cat'",
                  options={"type": "phrase", "config": "english"},
              )
              .execute()
          )
          ```
      - id: web-search
        name: Websearch
        description: |
          Uses PostgreSQL's `websearch_to_tsquery` function.
          This function will never raise syntax errors, which makes it possible to use raw user-supplied input for search, and can be used
          with advanced operators.

          - `unquoted text`: text not inside quote marks will be converted to terms separated by & operators, as if processed by plainto_tsquery.
          - `"quoted text"`: text inside quote marks will be converted to terms separated by <-> operators, as if processed by phraseto_tsquery.
          - `OR`: the word “or” will be converted to the | operator.
          - `-`: a dash will be converted to the ! operator.

        code: |
          ```python
          response = (
              supabase.table("quotes")
              .select("catchphrase")
              .text_search(
                  "catchphrase",
                  "'fat or cat'",
                  options={"type": "websearch", "config": "english"},
              )
              .execute()
          )
          ```

  - id: match
    title: match()
    description: |
      Match only rows where each column in `query` keys is equal to its associated value. Shorthand for multiple `.eq()`s.
    params:
      - name: query
        isOptional: false
        type: dict
        description: The object to filter with, with column names as keys mapped to their filter values
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .match({"id": 2, "name": "Albania"})
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 2,
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: not
    title: not_()
    description: |
      Match only rows which doesn't satisfy the filter. `not_` expects you to use the raw PostgREST syntax for the filter values.
    notes: |
      ```python
      .not_.in_('id', '(5,6,7)')  # Use `()` for `in` filter
      .not_.contains('arraycol', '{"a","b"}')  # Use `{}` for array values
      ```
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .not_.is_("name", "null")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Albania'),
              (2, null);
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: or
    title: or_()
    params:
      - name: filters
        isOptional: false
        type: string
        description: The filters to use, following PostgREST syntax
      - name: reference_table
        isOptional: true
        type: string
        description: Set this to filter on referenced tables instead of the parent table
    notes: |
      or_() expects you to use the raw PostgREST syntax for the filter names and values.

      ```python
      .or_('id.in.(5,6,7), arraycol.cs.{"a","b"}')  # Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
      .or_('id.in.(5,6,7), arraycol.cd.{"a","b"}')  # Use `cd` for `containedBy()`
      ```
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name")
              .or_("id.eq.2,name.eq.Algeria")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Albania"
              },
              {
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: use-or-with-and
        name: Use `or` with `and`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name")
              .or_("id.gt.3,and(id.eq.1,name.eq.Afghanistan)")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        reponse: |
          ```json
          {
            "data": [
              {
                "name": "Afghanistan"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
      - id: use-or-on-referenced-tables
        name: Use `or` on referenced tables
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name, cities!inner(name)")
              .or_("country_id.eq.1,name.eq.Beijing", reference_table="cities")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Germany",
                "cities": [
                  {
                    "name": "Munich"
                  }
                ]
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
  
  - id: filter
    title: filter()
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to filter on
      - name: operator
        isOptional: true
        type: string
        description: The operator to filter with, following PostgREST syntax
      - name: value
        isOptional: true
        type: any
        description: The value to filter with, following PostgREST syntax
    notes: |
      filter() expects you to use the raw PostgREST syntax for the filter values.

      ```python
      .filter('id', 'in', '(5,6,7)')  # Use `()` for `in` filter
      .filter('arraycol', 'cs', '{"a","b"}')  # Use `cs` for `contains()`, `{}` for array values
      ```
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .filter("name", "in", '("Algeria","Japan")')
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-a-foreign-table
        name: On a foreign table
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name, cities!inner(name)")
              .filter("cities.name", "eq", "Bali")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Germany'),
              (2, 'Indonesia');
            insert into
              cities (id, country_id, name)
            values
              (1, 2, 'Bali'),
              (2, 1, 'Munich');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Indonesia",
                "cities": [
                  {
                    "name": "Bali"
                  }
                ]
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
  - id: using-modifiers
    title: Using Modifiers
    description: |
      Filters work on the row level—they allow you to return rows that
      only match certain conditions without changing the shape of the rows.
      Modifiers are everything that don't fit that definition—allowing you to
      change the format of the response (e.g., returning a CSV string).

      Modifiers must be specified after filters. Some modifiers only apply for
      queries that return rows (e.g., `select()` or `rpc()` on a function that
      returns a table response).

  - id: order
    title: order()
    description: Order the query result by `column`.
    params:
      - name: column
        isOptional: false
        type: string
        description: The column to order by
      - name: desc
        isOptional: true
        type: bool
        description: Whether the rows should be ordered in descending order or not.
      - name: foreign_table
        isOptional: true
        type: string
        description: Foreign table name whose results are to be ordered.
      - name: nullsfirst
        isOptional: true
        type: bool
        description: Order by showing nulls first
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .order("name", desc=True)
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "id": 1,
                "name": "Afghanistan"
              },
              {
                "id": 2,
                "name": "Albania"
              },
              {
                "id": 3,
                "name": "Algeria"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-a-foreign-table
        name: On a foreign table
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name, cities(name)")
              .order("name", desc=True, foreign_table="cities")
              .execute()
          )
          ```
        data:
          sql: |
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'United States'),
              (2, 'Vanuatu');
            insert into
              cities (id, country_id, name)
            values
              (1, 1, 'Atlanta'),
              (2, 1, 'New York City');
        response: |
          ```json
          {
            "data": [
              {
                "name": "United States",
                "cities": [
                  {
                    "name": "New York City"
                  },
                  {
                    "name": "Atlanta"
                  }
                ]
              },
              {
                "name": "Vanuatu",
                "cities": []
              }
            ],
            "count": null
          }
          ```
        description: |
          Ordering on foreign tables doesn't affect the ordering of
          the parent table.
        hideCodeBlock: true
  - id: limit
    title: limit()
    params:
      - name: size
        isOptional: false
        type: number
        description: The maximum number of rows to return
      - name: foreign_table
        isOptional: true
        type: string
        description: Set this to limit rows of foreign tables instead of the parent table.
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("name").limit(1).execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Afghanistan"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-a-foreign-table
        name: On a foreign table
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name, cities(name)")
              .limit(1, foreign_table="cities")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'United States');
            insert into
              cities (id, country_id, name)
            values
              (1, 1, 'Atlanta'),
              (2, 1, 'New York City');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "United States",
                "cities": [
                  {
                    "name": "Atlanta"
                  }
                ]
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
  - id: range
    title: range()
    params:
      - name: start
        isOptional: false
        type: number
        description: The starting index from which to limit the result.
      - name: end
        isOptional: false
        type: number
        description: The last index to which to limit the result.
      - name: foreign_table
        isOptional: true
        type: string
        description: Set this to limit rows of foreign tables instead of the parent table.
    notes: |
      Limit the query result by starting at an offset (`from`) and ending at the offset (`from + to`). Only records within this range are returned. This respects the query order and if there is no order clause the range could behave unexpectedly.
      
      The `from` and `to` values are 0-based and inclusive: `range(1, 3)` will include the second, third and fourth rows of the query.
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("name").range(0, 1).execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Afghanistan"
              },
              {
                "name": "Albania"
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-a-foreign-table
        name: On a foreign table
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("name, cities(name)")
              .range(0, 1, foreign_table="cities")
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            create table
              cities (
                id int8 primary key,
                country_id int8 not null references countries,
                name text
              );

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            insert into
              cities (id, country_id, name)
            values
              (1, 1, 'Kabul'),
              (2, 1, 'Herat'),
              (3, 2, 'Berat');
            ```
        response: |
          ```json
          {
            "data": [
              {
                "name": "Afghanistan",
                "cities": [
                  {
                    "name": "Kabul"
                  },
                  {
                    "name": "Herat"
                  }
                ]
              },
              {
                "name": "Albania",
                "cities": [
                  {
                    "name": "Berat"
                  }
                ]
              },
              {
                "name": "Algeria",
                "cities": []
              }
            ],
            "count": null
          }
          ```
        hideCodeBlock: true
  - id: single
    title: single()
    notes: Return `data` as a single object instead of an array of objects.
    examples:
      - id: with-select()
        name: With `select()`
        code: |
          ```python
          response = supabase.table("countries").select("name").limit(1).single().execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": {
              "name": "Afghanistan"
            },
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: maybe-single
    title: maybe_single()
    notes: Return `data` as a single object instead of an array of objects.
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .eq("name", "Albania")
              .maybe_single()
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": {
              "id": 2,
              "name": "Albania"
            },
            "count": null
          }
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: csv
    title: csv()
    notes: Return `data` as a string in CSV format.
    examples:
      - id: return-data-as-csv
        name: Return data as CSV
        code: |
          ```python
          response = supabase.table("countries").select("*").csv().execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```json
          {
            "data": "id,name\n1,Afghanistan\n2,Albania\n3,Algeria",
            "count": null
          }
          ```
        description: |
          By default, the data is returned in JSON format, but can also be returned as Comma Separated Values.
        hideCodeBlock: true
        isSpotlight: true

  - id: explain
    title: Using Explain
    params:
      - name: wal
        isOptional: true
        type: boolean
        description: If `true`, include information on WAL record generation.
      - name: verbose
        isOptional: true
        type: boolean
        description: If `true`, the query identifier will be returned and `data` will include the output columns of the query.
      - name: settings
        isOptional: true
        type: boolean
        description: If `true`, include information on configuration parameters that affect query planning.
      - name: format
        isOptional: true
        type: boolean
        description: The format of the output, can be `"text"` (default) or `"json"`.
      - name: format
        isOptional: true
        type: '"text" | "json"'
        description: The format of the output, can be `"text"` (default) or `"json"`.
      - name: buffers
        isOptional: true
        type: boolean
        description: If `true`, include information on buffer usage.
      - name: analyze
        isOptional: true
        type: boolean
        description: If `true`, the query will be executed and the actual run time will be returned.
    description: |
      For debugging slow queries, you can get the [Postgres `EXPLAIN` execution plan](https://www.postgresql.org/docs/current/sql-explain.html) of a query
      using the `explain()` method. This works on any query, even for `rpc()` or writes.

      Explain is not enabled by default as it can reveal sensitive information about your database.
      It's best to only enable this for testing environments but if you wish to enable it for production you can provide additional protection by using a `pre-request` function.

      Follow the [Performance Debugging Guide](/docs/guides/database/debugging-performance) to enable the functionality on your project.
    examples:
      - id: get-execution-plan
        name: Get the execution plan
        code: |
          ```python
          response = supabase.table("countries").select("*").explain().execute()
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```
          Aggregate  (cost=33.34..33.36 rows=1 width=112)
            ->  Limit  (cost=0.00..18.33 rows=1000 width=40)
                  ->  Seq Scan on countries  (cost=0.00..22.00 rows=1200 width=40)
          ```
        description: |
          By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.
        hideCodeBlock: true
        isSpotlight: true

      - id: get-execution-plan-with-analyze-and-verbose
        name: Get the execution plan with analyze and verbose
        code: |
          ```python
          response = (
              supabase.table("countries")
              .select("*")
              .explain(analyze=True, verbose=True)
              .execute()
          )
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Afghanistan'),
              (2, 'Albania'),
              (3, 'Algeria');
            ```
        response: |
          ```
          Aggregate  (cost=33.34..33.36 rows=1 width=112) (actual time=0.041..0.041 rows=1 loops=1)
            Output: NULL::bigint, count(ROW(countries.id, countries.name)), COALESCE(json_agg(ROW(countries.id, countries.name)), '[]'::json), NULLIF(current_setting('response.headers'::text, true), ''::text), NULLIF(current_setting('response.status'::text, true), ''::text)
            ->  Limit  (cost=0.00..18.33 rows=1000 width=40) (actual time=0.005..0.006 rows=3 loops=1)
                  Output: countries.id, countries.name
                  ->  Seq Scan on public.countries  (cost=0.00..22.00 rows=1200 width=40) (actual time=0.004..0.005 rows=3 loops=1)
                        Output: countries.id, countries.name
          Query Identifier: -4730654291623321173
          Planning Time: 0.407 ms
          Execution Time: 0.119 ms
          ```
        description: |
          By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.
        hideCodeBlock: true
        isSpotlight: false

  - id: invoke
    title: 'invoke()'
    description: |
      Invoke a Supabase Function.
    notes: |
      - Requires an Authorization header.
      - When you pass in a body to your function, we automatically attach the Content-Type header for `Blob`, `ArrayBuffer`, `File`, `FormData` and `String`. If it doesn't match any of these types we assume the payload is `json`, serialise it and attach the `Content-Type` header as `application/json`. You can override this behaviour by passing in a `Content-Type` header of your own.
    examples:
      - id: invoke-function
        name: Basic invocation
        description:
        code: |
          ```python
          response = supabase.functions.invoke(
              "hello-world", invoke_options={"body": {"name": "Functions"}}
          )
          ```
      - id: error-handling
        name: Error handling
        description: |
          Returns one of the following errors:

          - `FunctionsHttpError`: if your function throws an error
          - `FunctionsRelayError`: if the Supabase Relay encounters an error processing your function
        isSpotlight: true
        code: |
          ```python
          from supafunc.errors import FunctionsRelayError, FunctionsHttpError

          try:
            response = supabase.functions.invoke(
                "hello-world",
                invoke_options={
                    "body": {"foo": "bar"},
                    "headers": {"my-custom-header": "my-custom-header-value"},
                },
            )
          except FunctionsHttpError as exception:
            err = exception.to_dict()
            print(f"Function returned an error {err.get("message")}")
          except FunctionsRelayError as exception:
            err = exception.to_dict()
            print(f"Relay error: {err.get("message")}")
          ```
      - id: passing-custom-headers
        name: Passing custom headers
        description: |
          The library accepts custom headers via the `headers` option. 

          Note: `supabase-py` automatically populates the `Authorization` header if there is a signed in user.
        isSpotlight: true
        code: |
          ```python
          response = supabase.functions.invoke(
            "hello-world", 
            invoke_options={
              "headers": {
                "my-custom-header": "my-custom-header-value"
              },
              "body": { "foo": "bar" }
            }
          )
          ```

  - id: list-buckets
    title: 'list_buckets()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: `select`
        - `objects` table permissions: none
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: list-buckets
        name: List buckets
        code: |
          ```
          res = supabase.storage.list_buckets()
          ```

  - id: get-bucket
    title: 'get_bucket()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: `select`
        - `objects` table permissions: none
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: get-bucket
        name: Get bucket
        code: |
          ```
          res = supabase.storage.get_bucket(name)
          ```

  - id: create-bucket
    title: 'create_bucket()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: `insert`
        - `objects` table permissions: none
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: create-bucket
        name: Create bucket
        code: |
          ```
          res = supabase.storage.create_bucket(name)
          ```

  - id: empty-bucket
    title: 'empty_bucket()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: `select`
        - `objects` table permissions: `select` and `delete`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: empty-bucket
        name: Empty bucket
        code: |
          ```
          res = supabase.storage.empty_bucket(name)
          ```
  - id: delete-bucket
    title: 'delete_bucket()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: `select` and `delete`
        - `objects` table permissions: none
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: delete-bucket
        name: Delete bucket
        code: |
          ```
          res = supabase.storage.delete_bucket(name)
          ```

  - id: from-upload
    title: 'from_.upload()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `insert`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
      - Please specify the appropriate content [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) if you are uploading images or audio. If no `file_options` are specified, the MIME type defaults to `text/html`.
    examples:
      - id: upload-file
        name: Upload file using filepath
        code: |
          ```py
          with open(filepath, 'rb') as f:
              supabase.storage.from_("testbucket").upload(file=f,path=path_on_supastorage, file_options={"content-type": "audio/mpeg"})
          ```
  - id: from-update
    title: from_.update()
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `update` and `select`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: update-file
        name: Update file
        code: |
          ```python
          with open(filepath, 'rb') as f:
            supabase.storage.from_("bucket_name").update(file=f, path=path_on_supastorage, file_options={"cache-control": "3600", "upsert": "true"})
          ```
  - id: from-move
    title: 'from_.move()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `update` and `select`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: move-file
        name: Move file
        code: |
          ```
          res = supabase.storage.from_('bucket_name').move('public/avatar1.png', 'private/avatar2.png')
          ```

  - id: from-create-signed-url
    title: 'from_.create_signed_url()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `select`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: create-signed-url
        name: Create Signed URL
        code: |
          ```
          res = supabase.storage.from_('bucket_name').create_signed_url(filepath, expiry_duration)
          ```

  - id: from-get-public-url
    title: 'from_.get_public_url()'
    notes: |
      - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/python/storage-updatebucket) or by going to Storage on [supabase.com/dashboard](https://supabase.com/dashboard), clicking the overflow menu on a bucket and choosing "Make public"
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: none
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: get-public-url
        name: Returns the URL for an asset in a public bucket
        code: |
          ```
          res = supabase.storage.from_('bucket_name').get_public_url('test/avatar1.jpg')
          ```

  - id: from-download
    title: 'from_.download()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `select`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: download-file
        name: Download file
        code: |
          ```
          with open(destination, 'wb+') as f:
            res = supabase.storage.from_('bucket_name').download(source)
            f.write(res)
          ```

  - id: from-remove
    title: 'from_.remove()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `delete` and `select`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: delete-file
        name: Delete file
        code: |
          ```
          res = supabase.storage.from_('bucket_name').remove('test.jpg')
          ```
  - id: from-list
    title: 'from_.list()'
    notes: |
      - RLS policy permissions required:
        - `buckets` table permissions: none
        - `objects` table permissions: `select`
      - Refer to the [Storage guide](/docs/guides/storage/security/access-control) on how access control works
    examples:
      - id: list-files
        name: List files in a bucket
        code: |
          ```
          res = supabase.storage.from_('bucket_name').list()
          ```