supabase/apps/docs/spec/supabase_dart_v2.yml

openref: 0.1

info:
  id: reference/dart
  title: Supabase Dart Client
  description: |

    Supabase Dart.
  slugPrefix: '/'
  specUrl: https://github.com/supabase/supabase/edit/master/apps/docs/spec/supabase_dart_v2.yml
  libraries:
    - name: 'Dart'
      id: 'dart'
      version: '0.0.1'

functions:
  - id: initializing
    title: 'Initializing'
    description: |
      You can initialize Supabase with the static `initialize()` method of the `Supabase` class.

      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: url
        isOptional: false
        type: string
        description: The unique Supabase URL which is supplied when you create a new project in your project dashboard.
      - name: publishableKey
        isOptional: false
        type: string
        description: The publishable (anon) key supplied when you create a new project in your project dashboard. Use this for client-side apps. The deprecated `anonKey` parameter is still accepted but `publishableKey` takes precedence when both are supplied.
      - name: headers
        isOptional: true
        type: Map<String, String>
        description: Custom header to be passed to the Supabase client.
      - name: httpClient
        isOptional: true
        type: Client
        description: Custom http client to be used by the Supabase client.
      - name: authOptions
        isOptional: true
        type: FlutterAuthClientOptions
        description: Options to change the Auth behaviors.
        subContent:
          - name: authFlowType
            isOptional: true
            type: AuthFlowType
            description: Whether to use the `pkce` flow or the `implicit` flow. Defaults to `pkce`.
          - name: localStorage
            isOptional: true
            type: LocalStorage
            description: Parameter to override the local storage to store auth tokens.
          - name: autoRefreshToken
            isOptional: true
            type: bool
            description: Whether to automatically refresh the token when it expires. Defaults to `true`.
      - name: postgrestOptions
        isOptional: true
        type: PostgrestClientOptions
        description: Options to change the Postgrest behaviors.
        subContent:
          - name: schema
            isOptional: true
            type: String
            description: Schema to query with the Supabase client. Defaults to `public`.
      - name: realtimeClientOptions
        isOptional: true
        type: RealtimeClientOptions
        description: Options to change the Realtime behaviors.
        subContent:
          - name: logLevel
            isOptional: true
            type: RealtimeLogLevel
            description: Level of realtime server logs to to be logged.
      - name: storageOptions
        isOptional: true
        type: StorageClientOptions
        description: Options to change the Storage behaviors.
        subContent:
          - name: retryAttempts
            isOptional: true
            type: int
            description: The number of times to retry a failed upload request. Defaults to `0`.
          - name: useNewHostname
            isOptional: true
            type: bool
            description: Whether to rewrite legacy storage URLs to use the dedicated storage host (`<ref>.storage.supabase.co`). Set to `true` only if your project has the dedicated storage host enabled. Defaults to `false`.
    examples:
      - id: flutter-initialize
        name: For Flutter
        code: |
          ```dart
          Future<void> main() async {
            await Supabase.initialize(
              url: 'https://xyzcompany.supabase.co',
              publishableKey: 'your-publishable-key',
            );

            runApp(MyApp());
          }

          // Get a reference your Supabase client
          final supabase = Supabase.instance.client;
          ```
      - id: for-other-dart-projects
        name: For other Dart projects
        code: |
          ```dart
          final supabase = SupabaseClient(
            'https://xyzcompany.supabase.co',
            'your-secret-key', // use your secret key for server-side usage
          );
          ```

  - id: auth-api
    title: 'Auth'
    category: Auth
  - id: sign-up
    title: 'signUp()'
    description: |
      Creates a new user.
    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.
      - When the user confirms their email address, they are redirected to the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls) by default. You can modify your `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
      - If signUp() 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.
    params:
      - name: email
        isOptional: true
        type: String
        description: User's email address to be used for email authentication.
      - name: phone
        isOptional: true
        type: String
        description: User's phone number to be used for phone authentication.
      - name: password
        isOptional: false
        type: String
        description: Password to be used for authentication.
      - name: emailRedirectTo
        isOptional: true
        type: String
        description: The URL to redirect the user to after they confirm their email address.
      - name: data
        isOptional: true
        type: Map<String, dynamic>
        description: The user's metadata to be stored in the user's object.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
      - name: channel
        isOptional: true
        type: OtpChannel
        description: Messaging channel to use (e.g. whatsapp or sms). Defaults to `OtpChannel.sms`.
    examples:
      - id: sign-up
        name: Sign up with an email and password
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.signUp(
            email: 'example@email.com',
            password: 'example-password',
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
        response: |
          ```json
          // Some fields may be null if "confirm email" is enabled.
          AuthResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: 'example@email.com',
                emailConfirmedAt: '2024-01-01T00:00:00Z',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {
                  'provider': 'email',
                  'providers': ['email']
                },
                userMetadata: {},
                identities: [
                  UserIdentity(
                    identityId: '22222222-2222-2222-2222-222222222222',
                    id: '11111111-1111-1111-1111-111111111111',
                    userId: '11111111-1111-1111-1111-111111111111',
                    identityData: {
                      'email': 'example@email.com',
                      'email_verified': false,
                      'phone_verified': false,
                      'sub': '11111111-1111-1111-1111-111111111111'
                    },
                    provider: 'email',
                    lastSignInAt: '2024-01-01T00:00:00Z',
                    createdAt: '2024-01-01T00:00:00Z',
                    updatedAt: '2024-01-01T00:00:00Z',
                  )
                ],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              ),
            ),
          );
          ```
      - id: sign-up-phone
        name: Sign up with a phone number and password (SMS)
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.signUp(
            phone: '123456789',
            password: 'example-password',
            channel: OtpChannel.sms,
          );
          ```
      - id: sign-up-with-metadata
        name: Sign up with additional metadata
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.signUp(
            email: 'example@email.com',
            password: 'example-password',
            data: {'username': 'my_user_name'},
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
      - id: sign-up-with-redirect-url
        name: Sign up with redirect URL
        isSpotlight: true
        description: |
          - See [redirect URLs and wildcards](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls) to add additional redirect URLs to your project.
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.signUp(
            email: 'example@email.com',
            password: 'example-password',
            emailRedirectTo: 'com.supabase.myapp://callback',
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
  - id: sign-in-anonymously
    title: 'signInAnonymously()'
    description: |
      Creates an anonymous user.
    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.
    params:
      - name: data
        isOptional: true
        type: Map<String, dynamic>
        description: The user's metadata to be stored in the user's object.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
    examples:
      - id: sign-in-anonymously
        name: Create an anonymous user
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.signInAnonymously();
          ```
        response: |
          ```json
          AuthResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: '',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {},
              userMetadata: {},
              identities: [],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
              isAnonymous: true,
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: '',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {},
                userMetadata: {},
                identities: [],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
                isAnonymous: true,
              ),
            ),
          );
          ```
      - id: sign-in-anonymously-with-user-metadata
        name: Create an anonymous user with custom user metadata
        isSpotlight: false
        code: |
          ```dart
          await supabase.auth.signInAnonymously(
            data: {'hello': 'world'},
          );
          ```
  - id: sign-in-with-password
    title: 'signInWithPassword()'
    description: |
      Log in an existing user using email or phone number with password.
    notes: |
      - Requires either an email and password or a phone number and password.
    params:
      - name: email
        isOptional: true
        type: String
        description: User's email address to be used for email authentication.
      - name: phone
        isOptional: true
        type: String
        description: User's phone number to be used for phone authentication.
      - name: password
        isOptional: false
        type: String
        description: Password to be used for authentication.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
    examples:
      - id: sign-in-with-email-and-password
        name: Sign in with email and password
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.signInWithPassword(
            email: 'example@email.com',
            password: 'example-password',
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
        response: |
          ```json
          AuthResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: 'example@email.com',
                emailConfirmedAt: '2024-01-01T00:00:00Z',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {
                  'provider': 'email',
                  'providers': ['email']
                },
                userMetadata: {},
                identities: [
                  UserIdentity(
                    identityId: '22222222-2222-2222-2222-222222222222',
                    id: '11111111-1111-1111-1111-111111111111',
                    userId: '11111111-1111-1111-1111-111111111111',
                    identityData: {
                      'email': 'example@email.com',
                      'email_verified': false,
                      'phone_verified': false,
                      'sub': '11111111-1111-1111-1111-111111111111'
                    },
                    provider: 'email',
                    lastSignInAt: '2024-01-01T00:00:00Z',
                    createdAt: '2024-01-01T00:00:00Z',
                    updatedAt: '2024-01-01T00:00:00Z',
                  )
                ],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              ),
            ),
          );
          ```
      - id: sign-in-with-phone-and-password
        name: Sign in with phone and password
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.signInWithPassword(
            phone: '+13334445555',
            password: 'example-password',
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
  - id: sign-in-with-otp
    title: 'signInWithOtp()'
    notes: |
      - Requires either an email or phone number.
      - This method is used for passwordless sign-ins where an OTP is sent to the user's email or phone number.
      - If you're using an email, you can configure whether you want the user to receive a magiclink or an OTP.
      - If you're using phone, you can configure whether you want the user to receive an OTP.
      - The magic link's destination URL is determined by the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls). You can modify the `SITE_URL` or add additional redirect urls in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
    params:
      - name: email
        isOptional: true
        type: String
        description: Email address to send the magic link or OTP to.
      - name: phone
        isOptional: true
        type: String
        description: Phone number to send the OTP to.
      - name: emailRedirectTo
        isOptional: true
        type: String
        description: The URL to redirect the user to after they click on the magic link.
      - name: shouldCreateUser
        isOptional: true
        type: bool
        description: If set to false, this method will not create a new user. Defaults to true.
      - name: data
        isOptional: true
        type: Map<String, dynamic>
        description: The user's metadata to be stored in the user's object.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
      - name: channel
        isOptional: true
        type: OtpChannel
        description: Messaging channel to use (e.g. whatsapp or sms). Defaults to `OtpChannel.sms`.
    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 an OTP or both. By default, a given user can only request an OTP once every 60 seconds.
          You can pass `emailRedirectTo` with a dynamic link to bring the users back to your app after they click on the magic link.
        code: |
          ```dart
          await supabase.auth.signInWithOtp(
            email: 'example@email.com',
            emailRedirectTo: kIsWeb ? null : 'io.supabase.flutter://signin-callback/',
          );
          ```
        response: |
          ```json
          AuthResponse(
            user: null,
            session: null,
          );
          ```
      - id: sign-in-with-sms-otp
        name: Sign in with SMS OTP.
        description: The user will be sent a SMS which contains an OTP. By default, a given user can only request an OTP once every 60 seconds.
        code: |
          ```dart
          await supabase.auth.signInWithOtp(
            phone: '+13334445555',
          );
          ```
      - id: sign-in-with-whatsapp-otp
        name: Sign in with WhatsApp OTP
        isSpotlight: false
        description: The user will be sent a WhatsApp message which contains an OTP. By default, a given user can only request an 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: |
          ```dart
          await supabase.auth.signInWithOtp(
            phone: '+13334445555',
            channel: OtpChannel.whatsapp,
          );
          ```
  - id: sign-in-with-id-token
    title: 'signInWithIdToken()'
    description: |
      Allows you to perform native Google, Apple, and Facebook sign in by combining it with [google_sign_in](https://pub.dev/packages/google_sign_in), [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple), or [flutter_facebook_auth](https://pub.dev/packages/flutter_facebook_auth) packages.
    params:
      - name: provider
        isOptional: false
        type: OAuthProvider
        description: The provider to perform the sign in with.
      - name: idToken
        isOptional: false
        type: String
        description: The identity token obtained from the third-party provider.
      - name: accessToken
        isOptional: true
        type: String
        description: Access token obtained from the third-party provider. Required for Google sign in.
      - name: nonce
        isOptional: true
        type: String
        description: Raw nonce value used to perform the third-party sign in. Required for Apple sign-in.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
    examples:
      - id: sign-in-with-google
        name: Native Google sign in
        isSpotlight: true
        description: |
          You can perform native Google sign in on Android and iOS using [google_sign_in](https://pub.dev/packages/google_sign_in).
          For platform specific settings, follow the instructions in the package README.

          First, create client IDs for your app. You need to create a web client ID as well to perform Google sign-in with Supabase.

          - [Steps to obtain web client ID](https://developers.google.com/identity/sign-in/android/start-integrating#configure_a_project)
          - [Steps to obtain Android client ID](https://developers.google.com/identity/sign-in/android/start-integrating#configure_a_project)
          - [Steps to obtain iOS client ID](https://developers.google.com/identity/sign-in/ios/start-integrating#get_an_oauth_client_id)

          Add the web client ID to the `Authentication -> Providers -> Google -> Client IDs` section in your Supabase dashboard
        code: |
          ```dart
          import 'package:google_sign_in/google_sign_in.dart';
          import 'package:supabase_flutter/supabase_flutter.dart';

          const webClientId = '<web client ID that you registered on Google Cloud, for example my-web.apps.googleusercontent.com>';

          const iosClientId = '<iOS client ID that you registered on Google Cloud, for example my-ios.apps.googleusercontent.com';

          final GoogleSignIn googleSignIn = GoogleSignIn(
            clientId: iosClientId,
            serverClientId: webClientId,
          );
          final googleUser = await googleSignIn.signIn();
          final googleAuth = await googleUser!.authentication;
          final accessToken = googleAuth.accessToken;
          final idToken = googleAuth.idToken;

          if (accessToken == null) {
            throw 'No Access Token found.';
          }
          if (idToken == null) {
            throw 'No ID Token found.';
          }

          final response = await supabase.auth.signInWithIdToken(
            provider: OAuthProvider.google,
            idToken: idToken,
            accessToken: accessToken,
          );
          ```
        response: |
          ```json
          AuthResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                ...
              },
              userMetadata: {
                ...
              },
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  provider: 'google',
                  ...
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: 'example@email.com',
                emailConfirmedAt: '2024-01-01T00:00:00Z',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {
                  ...
                },
                userMetadata: {
                  ...
                },
                identities: [
                  UserIdentity(
                    identityId: '22222222-2222-2222-2222-222222222222',
                    provider: 'google',
                    ...
                  )
                ],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              ),
            ),
          );
          ```
      - id: sign-in-with-apple
        name: Native Apple Sign in
        description: You need to [register your app ID with Apple](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/) with the `Sign In with Apple` capability selected, and add the bundle ID to your Supabase dashboard in `Authentication -> Providers -> Apple` before performing native Apple sign in.
        code: |
          ```dart
          import 'package:sign_in_with_apple/sign_in_with_apple.dart';
          import 'package:supabase_flutter/supabase_flutter.dart';
          import 'package:crypto/crypto.dart';

          /// Performs Apple sign in on iOS or macOS
          final rawNonce = supabase.auth.generateRawNonce();
          final hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();

          final credential = await SignInWithApple.getAppleIDCredential(
            scopes: [
              AppleIDAuthorizationScopes.email,
              AppleIDAuthorizationScopes.fullName,
            ],
            nonce: hashedNonce,
          );

          final idToken = credential.identityToken;
          if (idToken == null) {
            throw const AuthException(
              'Could not find ID Token from generated credential.',
            );
          }

          final response = await supabase.auth.signInWithIdToken(
            provider: OAuthProvider.apple,
            idToken: idToken,
            nonce: rawNonce,
          );
          ```
      - id: sign-in-with-facebook
        name: Native Facebook Sign in
        description: |
          You can perform native Facebook sign in using [flutter_facebook_auth](https://pub.dev/packages/flutter_facebook_auth).

          First, set up your Facebook app in the [Facebook Developer Console](https://developers.facebook.com) and configure it in your Supabase dashboard under `Authentication -> Providers -> Facebook`.
        code: |
          ```dart
          import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';
          import 'package:supabase_flutter/supabase_flutter.dart';

          Future<void> signInWithFacebook() async {
            final LoginResult result = await FacebookAuth.instance.login(
              permissions: ['public_profile', 'email'],
            );

            if (result.status == LoginStatus.success) {
              final accessToken = result.accessToken!.tokenString;

              final response = await supabase.auth.signInWithIdToken(
                provider: OAuthProvider.facebook,
                idToken: accessToken,
              );
            } else {
              throw const AuthException(
                'Facebook login failed: ${result.status}',
              );
            }
          }
          ```
  - id: sign-in-with-oauth
    title: 'signInWithOAuth()'
    description: |
      Signs the user in using third-party OAuth providers.
    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).
    params:
      - name: provider
        isOptional: false
        type: OAuthProvider
        description: The OAuth provider to use for signing in.
      - name: redirectTo
        isOptional: true
        type: String
        description: The URL to redirect the user to after they sign in with the third-party provider.
      - name: scopes
        isOptional: true
        type: String
        description: A list of scopes to request from the third-party provider.
      - name: authScreenLaunchMode
        isOptional: true
        type: LaunchMode
        description: The launch mode for the auth screen. Defaults to `LaunchMode.platformDefault`.
      - name: queryParams
        isOptional: true
        type: Map<String, String>
        description: Additional query parameters to be passed to the OAuth flow.
    examples:
      - id: sign-in-using-a-third-party-provider
        name: Sign in using a third-party provider
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.signInWithOAuth(
            OAuthProvider.github,
            redirectTo: kIsWeb ? null : 'my.scheme://my-host', // Optionally set the redirect link to bring back the user via deeplink.
            authScreenLaunchMode:
                kIsWeb ? LaunchMode.platformDefault : LaunchMode.externalApplication, // Launch the auth screen in a new webview on mobile.
          );
          ```
      - id: sign-in-with-custom-provider
        name: Sign in with a custom OIDC provider
        description: |
          `OAuthProvider` is now a class instead of an enum, allowing you to use custom OIDC providers by passing a custom provider string.
        isSpotlight: false
        code: |
          ```dart
          await supabase.auth.signInWithOAuth(
            OAuthProvider('custom:my-oidc-provider'),
            redirectTo: kIsWeb ? null : 'my.scheme://my-host',
          );
          ```
      - id: sign-in-using-a-third-party-provider-with-redirect
        name: With `redirectTo`
        description: |
          Specify the redirect link to bring back the user via deeplink.
          Note that `redirectTo` should be null for Flutter Web.
        code: |
          ```dart
          await supabase.auth.signInWithOAuth(
            OAuthProvider.github,
            redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
          );
          ```
      - id: sign-in-with-scopes
        name: With scopes
        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.
        code: |
          ```dart
          await supabase.auth.signInWithOAuth(
            OAuthProvider.github,
            scopes: 'repo gist notifications'
          );
          ...
          // after user comes back from signin flow

          final Session? session = supabase.auth.currentSession;
          final String? oAuthToken = session?.providerToken;
          ```
  - id: sign-in-with-sso
    title: 'signInWithSSO()'
    notes: |
      - Before you can call this method you need to [establish a connection](/docs/guides/auth/enterprise-sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this.
      - If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow.
      - In case you need to use a different way to start the authentication flow with an identity provider, you can use the `providerId` property. For example:
          - Mapping specific user email addresses with an identity provider.
          - Using different hints to identify the correct identity provider, like a company-specific page, IP address or other tracking information.
    params:
      - name: providerId
        isOptional: true
        type: String
        description: The ID of the SSO provider to use for signing in.
      - name: domain
        isOptional: true
        type: String
        description: The email domain to use for signing in.
      - name: redirectTo
        isOptional: true
        type: String
        description: The URL to redirect the user to after they sign in with the third-party provider.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
      - name: launchMode
        isOptional: true
        type: LaunchMode
        description: The launch mode for the auth screen. Defaults to `LaunchMode.platformDefault`.
    examples:
      - id: sign-in-with-domain
        name: Sign in with email domain
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.signInWithSSO(
            domain: 'company.com',
          );
          ```
      - id: sign-in-with-provider-uuid
        name: Sign in with provider UUID
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.signInWithSSO(
            providerId: '21648a9d-8d5a-4555-a9d1-d6375dc14e92',
          );
          ```
  - id: sign-in-with-web3
    title: 'signInWithWeb3()'
    description: |
      Signs in a user by verifying a message signed with their Web3 wallet.
    notes: |
      - Supports Ethereum (Sign-In with Ethereum) and Solana (Sign-In with Solana), both of which derive from the [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) standard.
      - Handle the wallet interaction and message signing yourself with the wallet library of your choice, then provide the signed `message` together with its `signature`.
      - For `Web3Chain.ethereum` the signature is a hex encoded string. For `Web3Chain.solana` it is a base64url encoded string.
      - On success, it signs the user in and returns a session. On failure, it throws an `AuthException`.
    params:
      - name: chain
        isOptional: false
        type: Web3Chain
        description: The blockchain used to sign in. One of `Web3Chain.ethereum` or `Web3Chain.solana`.
      - name: message
        isOptional: false
        type: String
        description: The EIP-4361 message that was signed by the user's wallet.
      - name: signature
        isOptional: false
        type: String
        description: The signature produced by the wallet. Hex encoded for Ethereum, base64url encoded for Solana.
      - name: captchaToken
        isOptional: true
        type: String
        description: The verification token received when the user completes the captcha on the app.
    examples:
      - id: sign-in-with-ethereum
        name: Sign in with an Ethereum wallet
        isSpotlight: true
        description: |
          Sign the EIP-4361 message with the user's Ethereum wallet, then pass the message and its hex encoded signature.
        code: |
          ```dart
          final response = await supabase.auth.signInWithWeb3(
            chain: Web3Chain.ethereum,
            message: message, // The EIP-4361 message signed by the wallet.
            signature: signature, // Hex encoded signature.
          );
          final session = response.session;
          ```
      - id: sign-in-with-solana
        name: Sign in with a Solana wallet
        description: |
          Sign the message with the user's Solana wallet, then pass the message and its base64url encoded signature.
        code: |
          ```dart
          final response = await supabase.auth.signInWithWeb3(
            chain: Web3Chain.solana,
            message: message, // The message signed by the wallet.
            signature: signature, // base64url encoded signature.
          );
          final session = response.session;
          ```
  - id: sign-in-with-passkey
    title: 'signInWithPasskey()'
    notes: |
      Signs the user in with a passkey (WebAuthn).
      - Available on `supabase_flutter` 2.15.0 and later as an extension on `GoTrueClient`.
      - Drives the full WebAuthn ceremony end to end: starts the challenge with the Supabase server, calls the `authenticator` you supply to prompt the user for biometrics or a security key, and verifies the credential with the server.
      - Does not require an existing session. On success the session is persisted and an `AuthChangeEvent.signedIn` event is fired.
      - `supabase_flutter` does not depend on a passkey plugin directly. Pass an implementation of `PasskeyAuthenticatorInterface`, such as the [`passkeys`](https://pub.dev/packages/passkeys) plugin's `PasskeyAuthenticator` (since `passkeys` `2.21.0`).
      - For native flows or custom UI, use the lower-level [`auth.passkey`](/docs/reference/dart/auth-passkey-api) namespace instead.
      - Passkeys are a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.
      - Platform setup the library cannot perform (Associated Domains on iOS/macOS, Digital Asset Links on Android, the `passkeys` web SDK on web) is documented in the `supabase_flutter` package README.
    params:
      - name: authenticator
        isOptional: false
        type: PasskeyAuthenticatorInterface
        description: Performs the platform passkey ceremony (FaceID/TouchID/security key). For example, a `PasskeyAuthenticator` from the `passkeys` package.
      - name: captchaToken
        isOptional: true
        type: String
        description: Captcha token to be used for captcha verification.
    examples:
      - id: sign-in-with-passkey
        name: Sign in with a passkey
        isSpotlight: true
        code: |
          ```dart
          import 'package:passkeys/authenticator.dart';

          final authenticator = PasskeyAuthenticator();

          final AuthResponse res = await supabase.auth.signInWithPasskey(authenticator);
          final Session? session = res.session;
          final User? user = res.user;
          ```
  - id: register-passkey
    title: 'registerPasskey()'
    notes: |
      Registers a new passkey (WebAuthn credential) for the signed in user.
      - Available on `supabase_flutter` 2.15.0 and later as an extension on `GoTrueClient`.
      - Drives the full WebAuthn ceremony end to end: starts the registration with the Supabase server, calls the `authenticator` you supply to create a credential on the device, and verifies it with the server.
      - Requires a signed in (non-anonymous) user. If the user has verified MFA factors, the session has to be at `aal2` to manage passkeys.
      - `supabase_flutter` does not depend on a passkey plugin directly. Pass an implementation of `PasskeyAuthenticatorInterface`, such as the [`passkeys`](https://pub.dev/packages/passkeys) plugin's `PasskeyAuthenticator` (since `passkeys` `2.21.0`).
      - For native flows or custom UI, use the lower-level [`auth.passkey`](/docs/reference/dart/auth-passkey-api) namespace instead.
      - Passkeys are a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.
    params:
      - name: authenticator
        isOptional: false
        type: PasskeyAuthenticatorInterface
        description: Performs the platform passkey ceremony (FaceID/TouchID/security key). For example, a `PasskeyAuthenticator` from the `passkeys` package.
      - name: friendlyName
        isOptional: true
        type: String
        description: Human readable name for the passkey. Used as a fallback for the WebAuthn `user.name`/`displayName` when the server omits them, and stored as the passkey's friendly name. Defaults to `Passkey` when not provided.
    examples:
      - id: register-passkey
        name: Register a passkey for the current user
        isSpotlight: true
        code: |
          ```dart
          import 'package:passkeys/authenticator.dart';

          final authenticator = PasskeyAuthenticator();

          final Passkey passkey = await supabase.auth.registerPasskey(
            authenticator,
            friendlyName: 'Work laptop',
          );
          ```
  - id: sign-out
    title: 'signOut()'
    description: |
      Signs out the current user, if there is a logged in user.
    notes: |
      - In order to use the `signOut()` method, the user needs to be signed in first.
    params:
      - name: scope
        isOptional: true
        type: SignOutScope
        description: Whether to sign out from all devices or just the current device. Defaults to `SignOutScope.local`.
    examples:
      - id: sign-out
        name: Sign out
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.signOut();
          ```
  - id: verify-otp
    title: 'verifyOtp()'
    notes: |
      - The `verifyOtp` 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: `email`, `recovery`, `invite` or `email_change` (`signup` and `magiclink` types are deprecated).
      - The verification type used should be determined based on the corresponding auth method called before `verifyOtp` to sign up or sign in a user.
    params:
      - name: token
        isOptional: false
        type: String
        description: The token that user was sent to their email or mobile phone
      - name: type
        isOptional: false
        type: OtpType
        description: Type of the OTP to verify
      - name: email
        isOptional: true
        type: String
        description: Email address that the OTP was sent to
      - name: phone
        isOptional: true
        type: String
        description: Phone number that the OTP was sent to
      - name: redirectTo
        isOptional: true
        type: String
        description: URI to redirect the user to after the OTP is verified
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification
      - name: tokenHash
        isOptional: true
        type: String
        description: Token used in an email link
    examples:
      - id: verify-signup-one-time-password(otp)
        name: Verify Signup One-Time Password (OTP)
        isSpotlight: false
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.verifyOTP(
            type: OtpType.signup,
            token: token,
            phone: '+13334445555',
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
        response: |
          ```json
          AuthResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: 'example@email.com',
                emailConfirmedAt: '2024-01-01T00:00:00Z',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {
                  'provider': 'email',
                  'providers': ['email']
                },
                userMetadata: {},
                identities: [
                  UserIdentity(
                    identityId: '22222222-2222-2222-2222-222222222222',
                    id: '11111111-1111-1111-1111-111111111111',
                    userId: '11111111-1111-1111-1111-111111111111',
                    identityData: {
                      'email': 'example@email.com',
                      'email_verified': false,
                      'phone_verified': false,
                      'sub': '11111111-1111-1111-1111-111111111111'
                    },
                    provider: 'email',
                    lastSignInAt: '2024-01-01T00:00:00Z',
                    createdAt: '2024-01-01T00:00:00Z',
                    updatedAt: '2024-01-01T00:00:00Z',
                  )
                ],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              ),
            ),
          );
          ```
      - id: verify-sms-one-time-password(otp)
        name: Verify SMS One-Time Password (OTP)
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.verifyOTP(
            type: OtpType.sms,
            token: '111111',
            phone: '+13334445555',
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
  - id: get-session
    title: 'currentSession'
    description: |
      Returns the session data, if there is an active session.
    notes: |
      - `currentSession` is a synchronous getter that returns whatever session is stored, even one whose access token has already expired.
      - `getSession()` is an asynchronous alternative that guarantees a valid access token when it resolves: a still-valid session is returned as-is, while an expired one is refreshed on demand first. It returns `null` when there is no session and throws an `AuthException` when an expired session cannot be refreshed.
    examples:
      - id: get-the-session-data
        name: Get the session data
        isSpotlight: true
        code: |
          ```dart
          final Session? session = supabase.auth.currentSession;
          ```
        response: |
          ```json
          Session(
            accessToken: '<ACCESS_TOKEN>',
            tokenType: 'bearer',
            expiresIn: 3600,
            refreshToken: '<REFRESH_TOKEN>',
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
          );
          ```
      - id: get-the-session-data-async
        name: Get the session data, refreshing if needed
        description: |
          Use the asynchronous `getSession()` to get a session whose access token is guaranteed to be valid, refreshing it on demand when it has expired.
        code: |
          ```dart
          final session = await supabase.auth.getSession();
          ```
  - id: get-user
    title: 'currentUser'
    description: |
      Returns the user data, if there is a logged in user.
    examples:
      - name: Get the logged in user
        isSpotlight: true
        code: |
          ```dart
          final User? user = supabase.auth.currentUser;
          ```
        response: |
          ```json
          User(
            id: '11111111-1111-1111-1111-111111111111',
            aud: 'authenticated',
            role: 'authenticated',
            email: 'example@email.com',
            emailConfirmedAt: '2024-01-01T00:00:00Z',
            phone: '',
            lastSignInAt: '2024-01-01T00:00:00Z',
            appMetadata: {
              'provider': 'email',
              'providers': ['email']
            },
            userMetadata: {},
            identities: [
              UserIdentity(
                identityId: '22222222-2222-2222-2222-222222222222',
                id: '11111111-1111-1111-1111-111111111111',
                userId: '11111111-1111-1111-1111-111111111111',
                identityData: {
                  'email': 'example@email.com',
                  'email_verified': false,
                  'phone_verified': false,
                  'sub': '11111111-1111-1111-1111-111111111111'
                },
                provider: 'email',
                lastSignInAt: '2024-01-01T00:00:00Z',
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              )
            ],
            createdAt: '2024-01-01T00:00:00Z',
            updatedAt: '2024-01-01T00:00:00Z',
          );
          ```
  - id: update-user
    title: 'updateUser()'
    description: |
      Updates user data for a logged in user.
    notes: |
      - In order to use the `updateUser()` method, the user needs to be signed in first.
      - By default, email updates sends a confirmation link to both the user's current and new email.
      To only send a confirmation link to the user's new email, disable **Secure email change** in your project's [email auth provider settings](https://supabase.com/dashboard/project/_/auth/providers).
    params:
      - name: attributes
        isOptional: false
        type: UserAttributes
        description: Attributes to update for the user.
        subContent:
          - name: email
            isOptional: true
            type: String
            description: The new email address for the user.
          - name: phone
            isOptional: true
            type: String
            description: The new phone number for the user.
          - name: password
            isOptional: true
            type: String
            description: The new password for the user.
          - name: data
            isOptional: true
            type: Map<String, dynamic>
            description: The user's metadata to be stored in the user's object.
          - name: nonce
            isOptional: true
            type: String
            description: The nonce sent for reauthentication if the user's password is to be updated.
          - name: currentPassword
            isOptional: true
            type: String
            description: The user's current password. Serialized as `current_password`. Required when changing the password and the auth server enforces the current password on password changes.
      - name: emailRedirectTo
        isOptional: true
        type: String
        description: The URI to redirect the user to after the email is updated.
    examples:
      - id: update-the-email-for-an-authenticated-user
        name: Update the email for an authenticated user
        description: Sends a "Confirm Email Change" email to the new email address.
        isSpotlight: true
        code: |
          ```dart
          final UserResponse res = await supabase.auth.updateUser(
            UserAttributes(
              email: 'example@email.com',
            ),
          );
          final User? updatedUser = res.user;
          ```
        response: |
          ```json
          UserResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
          );
          ```
      - id: update-the-password-for-an-authenticated-user
        name: Update the password for an authenticated user
        isSpotlight: false
        code: |
          ```dart
          final UserResponse res = await supabase.auth.updateUser(
            UserAttributes(
              password: 'new password',
            ),
          );
          final User? updatedUser = res.user;
          ```
      - id: update-the-password-with-current-password
        name: Update the password with the current password
        description: |
          When the auth server is configured to require the current password on password changes, pass it in `currentPassword`. It is serialized as `current_password` and used to verify the change.
        isSpotlight: false
        code: |
          ```dart
          final UserResponse res = await supabase.auth.updateUser(
            UserAttributes(
              password: 'new password',
              currentPassword: 'current password',
            ),
          );
          final User? updatedUser = res.user;
          ```
      - id: update-the-users-metadata
        name: Update the user's metadata
        isSpotlight: true
        code: |
          ```dart
          final UserResponse res = await supabase.auth.updateUser(
            UserAttributes(
              data: { 'hello': 'world' },
            ),
          );
          final User? updatedUser = res.user;
          ```
      - id: update-password-with-reauthentication
        name: Update the user's password with a nonce
        description: If "Secure password change" is enabled, updating the user's password requires a nonce. The nonce is sent to the user's email or phone number.
        isSpotlight: true
        code: |
          ```dart
          supabase.auth.updateUser(UserAttributes(
            email: 'example@email.com',
            nonce: '123456',
          ));
          ```
  - id: get-user-identities
    title: 'getUserIdentities()'
    description: |
      Gets all the identities linked to a user.
    notes: |
      - The user needs to be signed in to call `getUserIdentities()`.
    examples:
      - id: get-user-identities
        name: Returns a list of identities linked to the user
        isSpotlight: true
        code: |
          ```dart
          final identities = await supabase.auth.getUserIdentities();
          ```
        response: |
          ```json
          [
            UserIdentity(
              identityId: '22222222-2222-2222-2222-222222222222',
              id: '2024-01-01T00:00:00Z',
              userId: '2024-01-01T00:00:00Z',
              identityData: {
                'email': 'example@email.com',
                'email_verified': false,
                'phone_verified': false,
                'sub': '11111111-1111-1111-1111-111111111111'
              },
              provider: 'email',
              lastSignInAt: '2024-01-01T00:00:00Z',
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            )
          ];
          ```
  - id: link-identity
    title: 'linkIdentity()'
    description: |
      Links an oauth identity to an existing user. This method supports the PKCE flow.
    notes: |
      - The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).
      - The user needs to be signed in to call `linkIdentity()`.
      - If the candidate identity is already linked to the existing user or another user, `linkIdentity()` will fail.
    params:
      - name: provider
        isOptional: false
        type: OAuthProvider
        description: The provider to link the identity to.
      - name: redirectTo
        isOptional: true
        type: String
        description: The URL to redirect the user to after they sign in with the third-party provider.
      - name: scopes
        isOptional: true
        type: String
        description: A list of scopes to request from the third-party provider.
      - name: authScreenLaunchMode
        isOptional: true
        type: LaunchMode
        description: The launch mode for the auth screen. Defaults to `LaunchMode.platformDefault`.
      - name: queryParams
        isOptional: true
        type: Map<String, String>
        description: Additional query parameters to be passed to the OAuth flow.
    examples:
      - id: link-identity
        name: Link an identity to a user
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.linkIdentity(OAuthProvider.google);
          ```
  - id: unlink-identity
    title: 'unlinkIdentity()'
    description: |
      Unlinks an identity from a user by deleting it. The user will no longer be able to sign in with that identity once it's unlinked.
    params:
      - name: identity
        isOptional: false
        type: UserIdentity
        description: The user identity to unlink.
    notes: |
      - The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).
      - The user needs to be signed in to call `unlinkIdentity()`.
      - The user must have at least 2 identities in order to unlink an identity.
      - The identity to be unlinked must belong to the user.
    examples:
      - id: unlink-identity
        name: Unlink an identity
        isSpotlight: true
        code: |
          ```dart
          // retrieve all identities linked to a user
          final identities = await supabase.auth.getUserIdentities();

          // find the google identity
          final googleIdentity = identities.firstWhere(
            (element) => element.provider == 'google',
          );

          // unlink the google identity
          await supabase.auth.unlinkIdentity(googleIdentity);
          ```
  - id: link-identity-with-id-token
    title: 'linkIdentityWithIdToken()'
    description: |
      Links an identity to an existing user using an ID token obtained from a third-party OAuth provider. This allows linking identities using native OAuth flows (Google, Apple, Facebook, etc.) similar to `signInWithIdToken()` but for linking rather than signing in.
    notes: |
      - The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).
      - The user needs to be signed in to call `linkIdentityWithIdToken()`.
      - Supports the same OAuth providers as `signInWithIdToken()`: Google, Apple, Facebook, Kakao, and Keycloak.
      - If the candidate identity is already linked to another user, the operation will fail.
    params:
      - name: provider
        isOptional: false
        type: OAuthProvider
        description: The OAuth provider to link the identity from.
      - name: idToken
        isOptional: false
        type: String
        description: The identity token obtained from the third-party provider.
      - name: accessToken
        isOptional: true
        type: String
        description: Access token obtained from the third-party provider. Required for Google sign in.
      - name: nonce
        isOptional: true
        type: String
        description: Raw nonce value used to perform the third-party sign in. Required for Apple sign-in.
      - name: captchaToken
        isOptional: true
        type: String
        description: The captcha token to be used for captcha verification.
    examples:
      - id: link-google-identity
        name: Link Google identity
        isSpotlight: true
        description: |
          Link a Google identity to the currently signed-in user using native Google Sign-In.
        code: |
          ```dart
          import 'package:google_sign_in/google_sign_in.dart';
          import 'package:supabase_flutter/supabase_flutter.dart';

          const webClientId = '<web client ID>';
          const iosClientId = '<iOS client ID>';

          final GoogleSignIn googleSignIn = GoogleSignIn(
            clientId: iosClientId,
            serverClientId: webClientId,
          );
          final googleUser = await googleSignIn.signIn();
          final googleAuth = await googleUser!.authentication;
          final accessToken = googleAuth.accessToken;
          final idToken = googleAuth.idToken;

          if (accessToken == null) {
            throw 'No Access Token found.';
          }
          if (idToken == null) {
            throw 'No ID Token found.';
          }

          final response = await supabase.auth.linkIdentityWithIdToken(
            provider: OAuthProvider.google,
            idToken: idToken,
            accessToken: accessToken,
          );
          ```
      - id: link-apple-identity
        name: Link Apple identity
        description: |
          Link an Apple identity to the currently signed-in user using native Apple Sign In.
        code: |
          ```dart
          import 'package:sign_in_with_apple/sign_in_with_apple.dart';
          import 'package:supabase_flutter/supabase_flutter.dart';
          import 'package:crypto/crypto.dart';

          final rawNonce = supabase.auth.generateRawNonce();
          final hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();

          final credential = await SignInWithApple.getAppleIDCredential(
            scopes: [
              AppleIDAuthorizationScopes.email,
              AppleIDAuthorizationScopes.fullName,
            ],
            nonce: hashedNonce,
          );

          final idToken = credential.identityToken;
          if (idToken == null) {
            throw const AuthException(
              'Could not find ID Token from generated credential.',
            );
          }

          final response = await supabase.auth.linkIdentityWithIdToken(
            provider: OAuthProvider.apple,
            idToken: idToken,
            nonce: rawNonce,
          );
          ```
  - id: send-password-reauthentication
    title: 'reauthenticate()'
    notes: |
      - This method is used together with `updateUser()` when a user's password needs to be updated.
      - This method sends a nonce to the user's email. If the user doesn't have a confirmed email address, the method sends the nonce to the user's confirmed phone number instead.
    examples:
      - id: send-reauthentication-nonce
        name: Send reauthentication nonce
        description: Sends a reauthentication nonce to the user's email or phone number.
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.reauthenticate();
          ```
  - id: resend-email-or-phone-otps
    title: 'resend()'
    notes: |
      - Resends a signup confirmation, email change, or phone change email to the user.
      - Passwordless sign-ins can be resent by calling the `signInWithOtp()` method again.
      - Password recovery emails can be resent by calling the `resetPasswordForEmail()` method again.
      - This method only resend an email or phone OTP to the user if an initial signup, email change, or phone change request was made.
    examples:
      - id: resend-email-signup-confirmation
        name: Resend an email signup confirmation
        description: Resends the email signup confirmation to the user
        isSpotlight: true
        code: |
          ```dart
          final ResendResponse res = await supabase.auth.resend(
            type: OtpType.signup,
            email: 'email@example.com',
          );
          ```
  - id: on-auth-state-change
    title: 'onAuthStateChange()'
    description: |
      Receive a notification every time an auth event happens.
    notes: |
      - **You must provide an `onError` handler.** Network errors (e.g. an offline token refresh) are emitted as stream errors. If no `onError` is provided, Dart rethrows them as unhandled zone exceptions, crashing the app.
      - Auth event types: `initialSession`, `signedIn`, `signedOut`, `passwordRecovery`, `tokenRefreshed`, `userUpdated`, `userDeleted`, `mfaChallengeVerified`
    examples:
      - id: listen-to-auth-changes
        name: Listen to auth changes
        isSpotlight: true
        code: |
          ```dart
          final authSubscription = supabase.auth.onAuthStateChange.listen(
            (data) {
              final AuthChangeEvent event = data.event;
              final Session? session = data.session;
              // handle event
            },
            onError: (error, stackTrace) {
              // Network errors (e.g. offline) are emitted here.
              // Handle or log them to avoid an unhandled exception crash.
            },
          );
          ```
      - id: listen-to-a-specific-event
        name: Listen to a specific event
        code: |
          ```dart
          final authSubscription = supabase.auth.onAuthStateChange.listen(
            (data) {
              final AuthChangeEvent event = data.event;
              if (event == AuthChangeEvent.signedIn) {
                // handle signIn
              }
            },
            onError: (error, stackTrace) {
              // Handle or log network / auth errors here.
            },
          );
          ```
      - id: unsubscribe-from-auth-subscription
        name: Unsubscribe from auth subscription
        code: |
          ```dart
          final authSubscription = supabase.auth.onAuthStateChange.listen(
            (data) {},
            onError: (error, stackTrace) {},
          );

          authSubscription.cancel();
          ```
  - id: auth-reset-password-for-email
    title: 'resetPasswordForEmail()'
    description: |
      Sends a reset request to an email address.
    notes: |
      Sends a password reset request to an email address. When the user clicks the reset link in the email they are redirected back to your application. Prompt the user for a new password and call auth.updateUser():

      ```dart
      await supabase.auth.resetPasswordForEmail(
        'sample@email.com',
        redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
      );
      ```
    examples:
      - id: reset-password
        name: Reset password for Flutter
        isSpotlight: true
        code: |
          `redirectTo` is used to open the app via deeplink when user opens the password reset email.
          ```dart
          await supabase.auth.resetPasswordForEmail(
            'sample@email.com',
            redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
          );
          ```
  - id: set-session
    title: 'setSession()'
    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/guides/local-development/cli/config#auth.enable_refresh_token_rotation) is enabled by default on all projects to guard against replay attacks.
      - You can configure the [`REFRESH_TOKEN_REUSE_INTERVAL`](/docs/guides/local-development/cli/config#auth.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.
    params:
      - name: refreshToken
        isOptional: false
        type: String
        description: Refresh token to use to get a new session.
      - name: accessToken
        isOptional: true
        type: String
        description: Optional access token to set along with the refresh token.
    examples:
      - id: refresh-the-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.
        isSpotlight: true
        code: |
          ```dart
          final refreshToken = supabase.currentSession?.refreshToken ?? '';
          final AuthResponse response = await supabase.auth.setSession(refreshToken);

          final session = res.session;
          ```
      - id: set-session-with-access-token
        name: Set session with access token
        description: You can optionally provide an access token along with the refresh token.
        isSpotlight: false
        code: |
          ```dart
          final AuthResponse response = await supabase.auth.setSession(
            refreshToken,
            accessToken: accessToken,
          );
          ```
        response: |
          ```json
          AuthResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: 'example@email.com',
                emailConfirmedAt: '2024-01-01T00:00:00Z',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {
                  'provider': 'email',
                  'providers': ['email']
                },
                userMetadata: {},
                identities: [
                  UserIdentity(
                    identityId: '22222222-2222-2222-2222-222222222222',
                    id: '11111111-1111-1111-1111-111111111111',
                    userId: '11111111-1111-1111-1111-111111111111',
                    identityData: {
                      'email': 'example@email.com',
                      'email_verified': false,
                      'phone_verified': false,
                      'sub': '11111111-1111-1111-1111-111111111111'
                    },
                    provider: 'email',
                    lastSignInAt: '2024-01-01T00:00:00Z',
                    createdAt: '2024-01-01T00:00:00Z',
                    updatedAt: '2024-01-01T00:00:00Z',
                  )
                ],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              ),
            ),
          );
          ```
  - id: refresh-session
    title: 'refreshSession()'
    notes: |
      - This method will refresh and return a new session whether the current one is expired or not.
    examples:
      - id: refresh-session-using-the-current-session
        name: Refresh session using the current session
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.refreshSession();
          final session = res.session;
          ```
        response: |
          ```json
          AuthResponse(
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
            session: Session(
              accessToken: '<ACCESS_TOKEN>',
              tokenType: 'bearer',
              expiresIn: 3600,
              refreshToken: '<REFRESH_TOKEN>',
              user: const User(
                id: '11111111-1111-1111-1111-111111111111',
                aud: 'authenticated',
                role: 'authenticated',
                email: 'example@email.com',
                emailConfirmedAt: '2024-01-01T00:00:00Z',
                phone: '',
                lastSignInAt: '2024-01-01T00:00:00Z',
                appMetadata: {
                  'provider': 'email',
                  'providers': ['email']
                },
                userMetadata: {},
                identities: [
                  UserIdentity(
                    identityId: '22222222-2222-2222-2222-222222222222',
                    id: '11111111-1111-1111-1111-111111111111',
                    userId: '11111111-1111-1111-1111-111111111111',
                    identityData: {
                      'email': 'example@email.com',
                      'email_verified': false,
                      'phone_verified': false,
                      'sub': '11111111-1111-1111-1111-111111111111'
                    },
                    provider: 'email',
                    lastSignInAt: '2024-01-01T00:00:00Z',
                    createdAt: '2024-01-01T00:00:00Z',
                    updatedAt: '2024-01-01T00:00:00Z',
                  )
                ],
                createdAt: '2024-01-01T00:00:00Z',
                updatedAt: '2024-01-01T00:00:00Z',
              ),
            ),
          );
          ```
  - id: auth-mfa-api
    title: 'Overview'
    category: Auth
    subcategory: Auth MFA
    notes: |
      This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the `supabase.auth.mfa` namespace.

      Currently, Supabase supports time-based one-time password (TOTP) and phone verification code as the 2nd factor. Recovery codes are not supported but users can enroll multiple factors, with an upper limit of 10..

      Having a 2nd 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 factor.

      Learn more about implementing MFA on your application on our guide [here](https://supabase.com/docs/guides/auth/auth-mfa#overview).
  - id: mfa-enroll
    title: 'mfa.enroll()'
    notes: |
      Starts the enrollment process for a new Multi-Factor Authentication (MFA) factor. This method creates a new `unverified` factor.
      To verify a factor, present the QR code or secret to the user and ask them to add it to their authenticator app.
      The user has to enter the code from their authenticator app to verify it.
      - Use `totp` or `phone` as the `factorType` and the returned `id` to create a challenge.
      - To create a challenge, see [`mfa.challenge()`](/docs/reference/dart/auth-mfa-challenge).
      - To verify a challenge, see [`mfa.verify()`](/docs/reference/dart/auth-mfa-verify).
      - To create and verify a challenge in a single step, see [`mfa.challengeAndVerify()`](/docs/reference/dart/auth-mfa-challengeandverify).
    params:
      - name: factorType
        isOptional: true
        type: String
        description: Type of factor being enrolled.
      - name: issuer
        isOptional: true
        type: String
        description: Domain which the user is enrolled with.
      - name: friendlyName
        isOptional: true
        type: String
        description: Human readable name assigned to the factor.
      - name: phone
        isOptional: true
        type: String
        description: Phone number to enroll for phone factor type.
    examples:
      - id: enroll-totp-factor
        name: Enroll a time-based, one-time password (TOTP) factor
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.mfa.enroll(factorType: FactorType.totp);

          final qrCodeUrl = res.totp.qrCode;
          ```
        response: |
          ```json
          AuthMFAEnrollResponse(
            id: '<ID>',
            type: FactorType.totp,
            totp: TOTPEnrollment(
              qrCode: '<QR_CODE_AS_SVG_DATA>',
              secret: '<SECRET>',
              uri: '<URI>',
            ),
            phone: null,
          );
          ```
      - id: enroll-phone-factor
        name: Enroll a Phone Factor
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.mfa.enroll(factorType: FactorType.phone, phone: '+1234567890');

          final phone = res.phone;
          ```
        response: |
          ```json
          AuthMFAEnrollResponse(
            id: '<ID>',
            type: FactorType.phone,
            totp: null,
            phone: PhoneEnrollment(
              phone: '+1234567890',
            ),
          );
          ```
  - id: mfa-challenge
    title: 'mfa.challenge()'
    notes: |
      Prepares a challenge used to verify that a user has access to a MFA factor.
      - An [enrolled factor](/docs/reference/dart/auth-mfa-enroll) is required before creating a challenge.
      - To verify a challenge, see [`mfa.verify()`](/docs/reference/dart/auth-mfa-verify).
    params:
      - name: factorId
        isOptional: false
        type: String
        description: System assigned identifier for authenticator device as returned by enroll
      - name: channel
        isOptional: true
        type: OtpChannel
        description: Messaging channel to use for phone factors (e.g. `OtpChannel.whatsapp` or `OtpChannel.sms`). Defaults to the server's behavior (SMS) when omitted. Ignored for TOTP factors.
    examples:
      - id: create-mfa-challenge
        name: Create a challenge for a factor
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.mfa.challenge(
            factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
          );
          ```
        response: |
          ```json
          AuthMFAChallengeResponse(
            id: '<ID>',
            expiresAt: DateTime.fromMillisecondsSinceEpoch(1700000000),
          );
          ```
      - id: create-mfa-challenge-with-channel
        name: Create a challenge for a phone factor over WhatsApp
        description: |
          For phone factors you can choose the messaging channel used to deliver the verification code.
        code: |
          ```dart
          final res = await supabase.auth.mfa.challenge(
            factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
            channel: OtpChannel.whatsapp,
          );
          ```
  - id: mfa-verify
    title: 'mfa.verify()'
    notes: |
      Verifies a code against a challenge. The verification code is provided by the user by entering a code seen in their authenticator app.
      - To verify a challenge, please [create a challenge](/docs/reference/dart/auth-mfa-challenge) first.
    params:
      - name: factorId
        isOptional: false
        type: String
        description: System assigned identifier for authenticator device as returned by enroll
      - name: challengeId
        isOptional: false
        type: String
        description: The ID of the challenge to verify
      - name: code
        isOptional: false
        type: String
        description: The verification code on the user's authenticator app
    examples:
      - id: verify-challenge
        name: Verify a challenge for a factor
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.mfa.verify(
            factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
            challengeId: '4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15',
            code: '123456',
          );
          ```
        response: |
          ```json
          AuthMFAVerifyResponse(
            accessToken: '<ACCESS_TOKEN>',
            tokenType: 'Bearer',
            expiresIn: Duration(seconds: 3600),
            refreshToken: '<REFRESH_TOKEN>',
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
              isAnonymous: false,
              factors: [
                Factor(
                  id: '<ID>',
                  friendlyName: 'Important Auth App',
                  factorType: FactorType.totp,
                  status: 'verified',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z'
                )
              ]
            )
          );
          ```
  - id: mfa-challenge-and-verify
    title: 'mfa.challengeAndVerify()'
    notes: |
      Helper method which creates a challenge and immediately uses the given code to verify against it thereafter. The verification code is provided by the user by entering a code seen in their authenticator app.
      - An [enrolled factor](/docs/reference/dart/auth-mfa-enroll) is required before invoking `challengeAndVerify()`.
      - Executes [`mfa.challenge()`](/docs/reference/dart/auth-mfa-challenge) and [`mfa.verify()`](/docs/reference/dart/auth-mfa-verify) in a single step.
    params:
      - name: factorId
        isOptional: false
        type: String
        description: System assigned identifier for authenticator device as returned by enroll
      - name: code
        isOptional: false
        type: String
        description: The verification code on the user's authenticator app
    examples:
      - id: challenge-and-verify
        name: Create and verify a challenge for a factor
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.mfa.challengeAndVerify(
            factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
            code: '123456',
          );
          ```
        response: |
          ```json
          AuthMFAVerifyResponse(
            accessToken: '<ACCESS_TOKEN>',
            tokenType: 'Bearer',
            expiresIn: Duration(seconds: 3600),
            refreshToken: '<REFRESH_TOKEN>',
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                ),
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
              isAnonymous: false,
              factors: [
                Factor(
                  id: '<ID>',
                  friendlyName: 'Important Auth App',
                  factorType: FactorType.totp,
                  status: 'verified',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z'
                )
              ]
            )
          );
          ```
  - id: mfa-unenroll
    title: 'mfa.unenroll()'
    notes: |
      Unenroll removes a MFA factor.
      A user has to have an `aal2` authenticator level in order to unenroll a `verified` factor.
    params:
      - name: factorId
        isOptional: false
        type: String
        description: System assigned identifier for authenticator device as returned by enroll
    examples:
      - id: unenroll-a-factor
        name: Unenroll a factor
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.mfa.unenroll(
            '34e770dd-9ff9-416c-87fa-43b31d7ef225',
          );
          ```
        response: |
          ```json
          AuthMFAUnenrollResponse(
            id: '<FACTOR_ID>',
          );
          ```
  - id: mfa-get-authenticator-assurance-level
    title: 'mfa.getAuthenticatorAssuranceLevel()'
    notes: |
      Returns the Authenticator Assurance Level (AAL) for the active session.
      - Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism.
      - In Supabase, having an AAL of `aal1` means the user has signed in with their first factor, such as email, password, or OAuth sign-in. An AAL of `aal2` means the user has also signed in with their second factor, such as a time-based, one-time-password (TOTP).
      - If the user has a verified factor, the `nextLevel` field returns `aal2`. Otherwise, it returns `aal1`.
    examples:
      - id: get-aal
        name: Get the AAL details of a session
        isSpotlight: true
        code: |
          ```dart
          final res = supabase.auth.mfa.getAuthenticatorAssuranceLevel();
          final currentLevel = res.currentLevel;
          final nextLevel = res.nextLevel;
          final currentAuthenticationMethods = res.currentAuthenticationMethods;
          ```
        response: |
          ```json
          AuthMFAGetAuthenticatorAssuranceLevelResponse(
            currentLevel: AuthenticatorAssuranceLevels.aal1,
            nextLevel: AuthenticatorAssuranceLevels.aal2,
            currentAuthenticationMethods: [
              AMREntry(
                method: AMRMethod.password,
                timestamp: DateTime.fromMillisecondsSinceEpoch(1700000000000),
              )
            ]
          }
          ```
  - id: passkey-api
    title: 'Auth Passkey'
    category: Auth
    subcategory: Auth Passkey
    notes: |
      This section contains methods for WebAuthn passkey registration, authentication, and management. Methods are invoked behind the `supabase.auth.passkey` namespace.

      These methods expose the server side of the WebAuthn ceremony. The client side (the FaceID/TouchID/security key prompt) has to be performed with a platform passkey API: `navigator.credentials.create()`/`get()` on web, or a passkey plugin on iOS/Android/macOS. Options and credentials are exchanged as `Map<String, dynamic>` in the W3C WebAuthn Level 3 JSON format.

      For a one-call alternative that runs the full ceremony, see [`signInWithPasskey()`](/docs/reference/dart/auth-signinwithpasskey) and [`registerPasskey()`](/docs/reference/dart/auth-registerpasskey) on `supabase_flutter`.

      Passkey support is a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.
  - id: passkey-list
    title: 'passkey.list()'
    notes: |
      Returns the list of passkeys registered to the signed in user.
    examples:
      - id: list-passkeys
        name: List the current user's passkeys
        isSpotlight: true
        code: |
          ```dart
          final List<Passkey> passkeys = await supabase.auth.passkey.list();
          ```
  - id: passkey-update
    title: 'passkey.update()'
    notes: |
      Updates the friendly name of a passkey.
    params:
      - name: passkeyId
        isOptional: false
        type: String
        description: ID of the passkey to rename.
      - name: friendlyName
        isOptional: false
        type: String
        description: New human readable name for the passkey. Limited to 120 characters.
    examples:
      - id: rename-passkey
        name: Rename a passkey
        isSpotlight: true
        code: |
          ```dart
          final Passkey passkey = await supabase.auth.passkey.update(
            passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
            friendlyName: 'Work laptop',
          );
          ```
  - id: passkey-delete
    title: 'passkey.delete()'
    notes: |
      Deletes a passkey from the signed in user.
      - If the user has verified MFA factors, the session has to be at `aal2` to manage passkeys.
    params:
      - name: passkeyId
        isOptional: false
        type: String
        description: ID of the passkey to delete.
    examples:
      - id: delete-passkey
        name: Delete a passkey
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.passkey.delete(
            passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
          );
          ```
  - id: passkey-start-registration
    title: 'passkey.startRegistration()'
    notes: |
      Starts the registration of a new passkey for the signed in user.
      - Requires a signed in (non-anonymous) user.
      - Pass the returned `options` to the platform's passkey API to create the credential, then call [`passkey.verifyRegistration()`](/docs/reference/dart/auth-passkey-verifyregistration) with the result.
      - When the server omits `user.name`/`displayName` in the registration options, they are backfilled with `friendlyName` (or a generic `Passkey` default) before the platform ceremony.
    params:
      - name: friendlyName
        isOptional: true
        type: String
        description: Human readable name used as a fallback for the WebAuthn `user.name`/`displayName` when the server omits them. Defaults to `Passkey` when not provided.
    examples:
      - id: start-passkey-registration
        name: Start a passkey registration
        isSpotlight: true
        code: |
          ```dart
          final PasskeyRegistrationOptionsResponse registration =
              await supabase.auth.passkey.startRegistration(
            friendlyName: 'Work laptop',
          );

          // Hand registration.options to the platform passkey API.
          ```
  - id: passkey-verify-registration
    title: 'passkey.verifyRegistration()'
    notes: |
      Completes the registration of a new passkey and returns the stored [`Passkey`](/docs/reference/dart/auth-passkey-api).
    params:
      - name: challengeId
        isOptional: false
        type: String
        description: The challenge ID returned by `passkey.startRegistration()`.
      - name: credential
        isOptional: false
        type: 'Map<String, dynamic>'
        description: The credential created by the platform's passkey API, serialized in the W3C `RegistrationResponseJSON` format.
    examples:
      - id: verify-passkey-registration
        name: Verify a passkey registration
        isSpotlight: true
        code: |
          ```dart
          final Passkey passkey = await supabase.auth.passkey.verifyRegistration(
            challengeId: registration.challengeId,
            credential: credential,
          );
          ```
  - id: passkey-start-authentication
    title: 'passkey.startAuthentication()'
    notes: |
      Starts a passkey sign in.
      - Does not require an existing session.
      - Pass the returned `options` to the platform's passkey API to obtain an assertion, then call [`passkey.verifyAuthentication()`](/docs/reference/dart/auth-passkey-verifyauthentication) with the result.
    params:
      - name: captchaToken
        isOptional: true
        type: String
        description: Captcha token to be used for captcha verification.
    examples:
      - id: start-passkey-authentication
        name: Start a passkey sign in
        isSpotlight: true
        code: |
          ```dart
          final PasskeyAuthenticationOptionsResponse authentication =
              await supabase.auth.passkey.startAuthentication();

          // Hand authentication.options to the platform passkey API.
          ```
  - id: passkey-verify-authentication
    title: 'passkey.verifyAuthentication()'
    notes: |
      Completes a passkey sign in and returns the new session.
      - On success the session is persisted and an `AuthChangeEvent.signedIn` event is fired.
    params:
      - name: challengeId
        isOptional: false
        type: String
        description: The challenge ID returned by `passkey.startAuthentication()`.
      - name: credential
        isOptional: false
        type: 'Map<String, dynamic>'
        description: The assertion produced by the platform's passkey API, serialized in the W3C `AuthenticationResponseJSON` format.
    examples:
      - id: verify-passkey-authentication
        name: Verify a passkey sign in
        isSpotlight: true
        code: |
          ```dart
          final AuthResponse res = await supabase.auth.passkey.verifyAuthentication(
            challengeId: authentication.challengeId,
            credential: credential,
          );
          final Session? session = res.session;
          final User? user = res.user;
          ```
  - id: oauth-server-api
    title: 'OAuth Server'
    category: Auth
    subcategory: OAuth Server
    notes: |
      Methods under the `supabase.auth.oauth` namespace are used when your Supabase project acts as an OAuth 2.1 server. They drive the user-facing consent flow and require a signed-in user. The OAuth 2.1 server feature must be enabled in your Supabase Auth configuration.
  - id: oauth-get-authorization-details
    title: 'oauth.getAuthorizationDetails()'
    notes: |
      Retrieves details about a pending OAuth authorization request so you can render a consent screen. The `authorizationId` is provided as a query parameter on the redirect URL that starts the flow.
      - Returns a sealed `OAuthAuthorizationResponse`. Handle both variants: `OAuthAuthorizationDetailsResponse` carries the requesting `client` and requested `scope` for the consent screen, while `OAuthAuthorizationRedirectResponse` is returned when the user has already granted consent and only carries a `redirectUrl` to forward to.
    params:
      - name: authorizationId
        isOptional: false
        type: String
        description: The unique identifier of the pending authorization request.
    examples:
      - id: get-authorization-details
        name: Get authorization details
        isSpotlight: true
        code: |
          ```dart
          final authorizationId =
              Uri.parse(currentUrl).queryParameters['authorization_id']!;

          final response =
              await supabase.auth.oauth.getAuthorizationDetails(authorizationId);

          switch (response) {
            case OAuthAuthorizationRedirectResponse(:final redirectUrl):
              // The user already consented; forward them without a consent screen.
              break;
            case OAuthAuthorizationDetailsResponse(:final client, :final scope):
              // Render a consent screen for `client` requesting `scope`.
              break;
          }
          ```
  - id: oauth-approve-authorization
    title: 'oauth.approveAuthorization()'
    notes: |
      Approves a pending OAuth authorization request on behalf of the signed-in user. The response contains the redirect URL the user should be sent to.
    params:
      - name: authorizationId
        isOptional: false
        type: String
        description: The unique identifier of the pending authorization request.
    examples:
      - id: approve-authorization
        name: Approve authorization
        isSpotlight: true
        code: |
          ```dart
          final consent =
              await supabase.auth.oauth.approveAuthorization(authorizationId);
          // Redirect the user to consent.redirectUrl
          ```
  - id: oauth-deny-authorization
    title: 'oauth.denyAuthorization()'
    notes: |
      Denies a pending OAuth authorization request on behalf of the signed-in user. The response contains the redirect URL the user should be sent to.
    params:
      - name: authorizationId
        isOptional: false
        type: String
        description: The unique identifier of the pending authorization request.
    examples:
      - id: deny-authorization
        name: Deny authorization
        isSpotlight: true
        code: |
          ```dart
          final consent =
              await supabase.auth.oauth.denyAuthorization(authorizationId);
          // Redirect the user to consent.redirectUrl
          ```
  - id: oauth-list-grants
    title: 'oauth.listGrants()'
    description: |
      Lists the OAuth grants the signed-in user has issued to third-party OAuth clients.
    notes: |
      - Requires an authenticated user. Returns the grants issued by the current user.
    examples:
      - id: list-oauth-grants
        name: List OAuth grants
        isSpotlight: true
        code: |
          ```dart
          final List<OAuthGrant> grants = await supabase.auth.oauth.listGrants();

          for (final grant in grants) {
            print('${grant.client.clientId}: ${grant.scopes}');
          }
          ```
  - id: oauth-revoke-grant
    title: 'oauth.revokeGrant()'
    description: |
      Revokes a grant the signed-in user previously issued to a third-party OAuth client.
    params:
      - name: clientId
        isOptional: false
        type: String
        description: The identifier of the OAuth client whose grant should be revoked.
    examples:
      - id: revoke-oauth-grant
        name: Revoke an OAuth grant
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.oauth.revokeGrant('client-id');
          ```
  - id: admin-api
    title: 'Overview'
    category: Auth
    subcategory: Auth Admin
    notes: |
      - Any method under the `supabase.auth.admin` namespace requires a `secret` key.
      - These methods are considered admin methods and should be called on a trusted server. Never expose your `secret` key in the Flutter app.
    examples:
      - id: create-auth-admin-client
        name: Create server-side auth client
        isSpotlight: true
        code: |
          ```dart
          final supabase = SupabaseClient(supabaseUrl, secretKey);
          ```
  - id: get-user-by-id
    title: 'getUserById()'
    notes: |
      Get user by id.
      - Fetches the user object from the database based on the user's id.
      - The `getUserById()` method requires the user's id which maps to the `auth.users.id` column.
    params:
      - name: uid
        isOptional: false
        type: String
        description: User ID of the user to fetch.
    examples:
      - id: fetch-the-user-object-using-the-access-token-jwt
        name: Fetch the user object using the access_token jwt
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.admin.getUserById(userId);
          final user = res.user;
          ```
        response: |
          ```json
          UserResponse(
            user: const User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
          );
          ```
  - id: list-users
    title: 'listUsers()'
    notes: |
      Get a list of users.
      - Defaults to return 50 users per page.
    params:
      - name: page
        isOptional: true
        type: int
        description: What page of users to return.
      - name: page
        isOptional: true
        type: int
        description: How many users to be returned per page. Defaults to 50.
    examples:
      - id: get-a-full-list-of-users
        name: Get a page of users
        isSpotlight: true
        code: |
          ```dart
          // Returns the first 50 users.
          final List<User> users = await supabase.auth.admin.listUsers();
          ```
        response: |
          ```json
          [
            User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'example@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'example@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            )
          ]
          ```
      - id: get-paginated-list-of-users
        name: Paginated list of users
        isSpotlight: false
        code: |
          ```dart
          // Returns the 101th - 200th users.
          final List<User> res = await supabase.auth.admin.listUsers(
            page: 2,
            perPage: 100,
          );
          ```
  - id: create-user
    title: 'createUser()'
    notes: |
      Creates a new user.
      - To confirm the user's email address or phone number, set `email_confirm` or `phone_confirm` to true. Both arguments default to false.
      - `createUser()` will not send a confirmation email to the user. You can use [`inviteUserByEmail()`](/docs/reference/dart/auth-admin-inviteuserbyemail) if you want to send them an email invite instead.
      - If you are sure that the created user's email or phone number is legitimate and verified, you can set the `email_confirm` or `phone_confirm` param to `true`.
    params:
      - name: attributes
        isOptional: false
        type: AdminUserAttributes
        description: Attributes to create the user with.
        subContent:
          - name: email
            isOptional: false
            type: String
            description: The email address of the user.
          - name: password
            isOptional: false
            type: String
            description: The password of the user.
          - name: phone
            isOptional: true
            type: String
            description: The phone number of the user.
          - name: userMetadata
            isOptional: true
            type: Map<String, dynamic>
            description: A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column.
          - name: appMetadata
            isOptional: true
            type: Map<String, dynamic>
            description: A custom data object to store the user's application specific metadata. This maps to the `auth.users.app_metadata` column.
          - name: emailConfirm
            isOptional: true
            type: bool
            description: Whether to confirm the user's email address.
          - name: phoneConfirm
            isOptional: true
            type: bool
            description: Whether to confirm the user's phone number.
          - name: banDuration
            isOptional: true
            type: String
            description: Determines how long a user is banned for. Some possible durations include '300ms', '2h45m'.
    examples:
      - id: create-a-new-user-with-custom-user-metadata
        name: With custom user metadata
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.admin.createUser(AdminUserAttributes(
            email: 'user@email.com',
            password: 'password',
            userMetadata: {'name': 'Yoda'},
          ));
          ```
        response: |
          ```json
          UserResponse(
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'user@email.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {'name': 'Yoda'},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'user@email.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
          );
          ```
      - id: auto-confirm-the-users-email
        name: Auto-confirm the user's email
        code: |
          ```dart
          final res = await supabase.auth.admin.createUser(AdminUserAttributes(
            email: 'user@email.com',
            emailConfirm: true,
          ));
          ```
      - id: auto-confirm-the-users-phone-number
        name: Auto-confirm the user's phone number
        code: |
          ```dart
          final res = await supabase.auth.admin.createUser(AdminUserAttributes(
            phone: '1234567890',
            phoneConfirm: true,
          ));
          ```
  - id: delete-user
    title: 'deleteUser()'
    notes: |
      Delete a user.
      - The `deleteUser()` method requires the user's ID, which maps to the `auth.users.id` column.
      - When `shouldSoftDelete` is `true`, the user is soft-deleted: their record and associated data are retained but the user is marked as deleted. Defaults to `false`, which permanently removes the user.
    params:
      - name: id
        isOptional: false
        type: String
        description: ID of the user to be deleted.
      - name: shouldSoftDelete
        isOptional: true
        type: bool
        description: If true, soft-deletes the user (keeps the record but marks it deleted). Defaults to false (permanent delete).
    examples:
      - id: removes-a-user
        name: Removes a user
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.admin
              .deleteUser('715ed5db-f090-4b8c-a067-640ecee36aa0');
          ```
      - id: soft-delete-a-user
        name: Soft-delete a user
        code: |
          ```dart
          await supabase.auth.admin
              .deleteUser(
                '715ed5db-f090-4b8c-a067-640ecee36aa0',
                shouldSoftDelete: true,
              );
          ```
  - id: invite-user-by-email
    title: 'inviteUserByEmail()'
    notes: |
      Sends an invite link to the user's email address.
    params:
      - name: email
        isOptional: false
        type: String
        description: Email address of the user to invite.
      - name: redirectTo
        isOptional: true
        type: String
        description: URI to redirect the user to after they open the invite link.
      - name: data
        isOptional: true
        type: Map<String, dynamic>
        description: A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column.
    examples:
      - id: invite-a-user
        name: Invite a user
        isSpotlight: true
        code: |
          ```dart
          final UserResponse res = await supabase.auth.admin
              .inviteUserByEmail('email@example.com');
          final User? user = res.user;
          ```
        response: |
          ```json
          UserResponse(
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'email@example.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'email@example.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            ),
          );
          ```
  - id: generate-link
    title: 'generateLink()'
    notes: |
      Generates email links and OTPs. This will not send links or OTPs to the end user. This function is for custom admin functionality.
      - The following types can be passed into `generateLink()`: `signup`, `magiclink`, `invite`, `recovery`, `emailChangeCurrent`, `emailChangeNew`, `phoneChange`.
      - `generateLink()` only generates the email link for `email_change_email` if the "Secure email change" setting is enabled under the "Email" provider in your Supabase project.
      - `generateLink()` handles the creation of the user for `signup`, `invite` and `magiclink`.
    params:
      - name: type
        isOptional: false
        type: GenerateLinkType
        description: The type of invite link to generate.
      - name: email
        isOptional: false
        type: String
        description: Email address of the user to invite.
      - name: password
        isOptional: true
        type: String
        description: Password for the user. Required for `signup` type.
      - name: redirectTo
        isOptional: true
        type: String
        description: URI to redirect the user to after they open the invite link.
      - name: data
        isOptional: true
        type: Map<String, dynamic>
        description: A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column.
    examples:
      - id: generate-a-signup-link
        name: Generate a signup link
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.auth.admin.generateLink(
            type: GenerateLinkType.signup,
            email: 'email@example.com',
            password: 'secret',
          );
          final actionLink = res.properties.actionLink;
          ```
        response: |
          ```json
          GenerateLinkResponse(
            properties: GenerateLinkProperties(
              actionLink: '<LINK_TO_SEND_TO_USER>',
              emailOtp: '999999',
              hashedToken: '<HASHED_TOKEN',
              redirectTo: '<REDIRECT_URL>',
              verificationType: GenerateLinkType.signup
            ),
            user: User(
              id: '11111111-1111-1111-1111-111111111111',
              aud: 'authenticated',
              role: 'authenticated',
              email: 'email@example.com',
              emailConfirmedAt: '2024-01-01T00:00:00Z',
              phone: '',
              lastSignInAt: '2024-01-01T00:00:00Z',
              appMetadata: {
                'provider': 'email',
                'providers': ['email']
              },
              userMetadata: {},
              identities: [
                UserIdentity(
                  identityId: '22222222-2222-2222-2222-222222222222',
                  id: '11111111-1111-1111-1111-111111111111',
                  userId: '11111111-1111-1111-1111-111111111111',
                  identityData: {
                    'email': 'email@example.com',
                    'email_verified': false,
                    'phone_verified': false,
                    'sub': '11111111-1111-1111-1111-111111111111'
                  },
                  provider: 'email',
                  lastSignInAt: '2024-01-01T00:00:00Z',
                  createdAt: '2024-01-01T00:00:00Z',
                  updatedAt: '2024-01-01T00:00:00Z',
                )
              ],
              createdAt: '2024-01-01T00:00:00Z',
              updatedAt: '2024-01-01T00:00:00Z',
            )
          )
          ```
  - id: update-user-by-id
    title: 'updateUserById()'
    params:
      - name: uid
        isOptional: false
        type: GenerateLinkType
        description: User ID of the user to update.
      - name: attributes
        isOptional: false
        type: AdminUserAttributes
        description: Attributes to update for the user.
        subContent:
          - name: email
            isOptional: false
            type: String
            description: The email address of the user.
          - name: password
            isOptional: false
            type: String
            description: The password of the user.
          - name: phone
            isOptional: true
            type: String
            description: The phone number of the user.
          - name: userMetadata
            isOptional: true
            type: Map<String, dynamic>
            description: A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column.
          - name: appMetadata
            isOptional: true
            type: Map<String, dynamic>
            description: A custom data object to store the user's application specific metadata. This maps to the `auth.users.app_metadata` column.
          - name: emailConfirm
            isOptional: true
            type: bool
            description: Whether to confirm the user's email address.
          - name: phoneConfirm
            isOptional: true
            type: bool
            description: Whether to confirm the user's phone number.
          - name: banDuration
            isOptional: true
            type: String
            description: Determines how long a user is banned for. Some possible durations include '300ms', '2h45m'.
    examples:
      - id: updates-a-users-email
        name: Updates a user's email
        isSpotlight: false
        code: |
          ```dart
          await supabase.auth.admin.updateUserById(
            '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
            attributes: AdminUserAttributes(
              email: 'new@email.com',
            ),
          );
          ```
  - id: admin-passkey-api
    title: 'Passkey Admin API'
    category: Auth
    subcategory: Passkey Admin
    notes: |
      Contains passkey administration methods, accessed under the `supabase.auth.admin.passkey` namespace. Requires a `secret` key.

      Passkey support is a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.
  - id: admin-list-passkeys
    title: 'admin.passkey.listPasskeys()'
    notes: |
      Returns the list of passkeys registered to the user with the given ID.
    params:
      - name: userId
        isOptional: false
        type: String
        description: User ID whose passkeys should be returned.
    examples:
      - id: admin-list-passkeys
        name: List a user's passkeys
        isSpotlight: true
        code: |
          ```dart
          final List<Passkey> passkeys = await supabase.auth.admin.passkey.listPasskeys(
            userId: '11111111-1111-1111-1111-111111111111',
          );
          ```
  - id: admin-delete-passkey
    title: 'admin.passkey.deletePasskey()'
    notes: |
      Deletes a passkey from a user.
    params:
      - name: userId
        isOptional: false
        type: String
        description: User ID that owns the passkey.
      - name: passkeyId
        isOptional: false
        type: String
        description: ID of the passkey to delete.
    examples:
      - id: admin-delete-passkey
        name: Delete a user's passkey
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.admin.passkey.deletePasskey(
            userId: '11111111-1111-1111-1111-111111111111',
            passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
          );
          ```
  - id: admin-custom-providers-api
    title: 'Custom OIDC/OAuth Provider Admin API'
    category: Auth
    subcategory: Custom Provider Admin
    notes: |
      - Methods under the `supabase.auth.admin.customProviders` namespace manage custom OIDC/OAuth providers programmatically. Requires a `secret` key.
      - These are admin methods and should be called on a trusted server. Never expose your `secret` key in the Flutter app.
      - Custom providers are referenced with a `custom:` prefix when signing in (for example `custom:mycompany`), and are distinct from the OAuth 2.1 server clients managed through `supabase.auth.admin.oauth`.
  - id: admin-custom-providers-list
    title: 'admin.customProviders.listProviders()'
    notes: |
      Lists all custom providers, optionally filtered by provider type.
    params:
      - name: type
        isOptional: true
        type: CustomProviderType
        description: When set, only providers of this type are returned. Either `CustomProviderType.oauth2` or `CustomProviderType.oidc`.
    examples:
      - id: list-custom-providers
        name: List custom providers
        isSpotlight: true
        code: |
          ```dart
          final List<CustomOAuthProvider> providers =
              await supabase.auth.admin.customProviders.listProviders();
          ```
  - id: admin-custom-providers-create
    title: 'admin.customProviders.createProvider()'
    notes: |
      Creates a new custom OIDC/OAuth provider. For OIDC providers, the server fetches and validates the discovery document at creation time and throws an `AuthException` with code `validation_failed` if it is unreachable or invalid.
    params:
      - name: params
        isOptional: false
        type: CreateCustomProviderParams
        description: The provider configuration, including `providerType`, `identifier`, `name`, `clientId`, `clientSecret`, and optional fields such as `customClaimsAllowlist`.
    examples:
      - id: create-custom-provider
        name: Create a custom provider
        isSpotlight: true
        code: |
          ```dart
          final CustomOAuthProvider provider =
              await supabase.auth.admin.customProviders.createProvider(
            CreateCustomProviderParams(
              providerType: CustomProviderType.oidc,
              identifier: 'custom:mycompany',
              name: 'My Company',
              clientId: 'client-id',
              clientSecret: 'client-secret',
              issuer: 'https://auth.mycompany.com',
              customClaimsAllowlist: ['groups', 'org_id'],
            ),
          );
          ```
  - id: admin-custom-providers-get
    title: 'admin.customProviders.getProvider()'
    notes: |
      Gets details of a specific custom provider by its identifier.
    params:
      - name: identifier
        isOptional: false
        type: String
        description: The provider identifier, for example `custom:mycompany`.
    examples:
      - id: get-custom-provider
        name: Get a custom provider
        isSpotlight: true
        code: |
          ```dart
          final CustomOAuthProvider provider =
              await supabase.auth.admin.customProviders.getProvider('custom:mycompany');
          ```
  - id: admin-custom-providers-update
    title: 'admin.customProviders.updateProvider()'
    notes: |
      Updates an existing custom provider. When `issuer` or `discoveryUrl` changes on an OIDC provider, the server re-fetches and validates the discovery document before persisting.
    params:
      - name: identifier
        isOptional: false
        type: String
        description: The provider identifier, for example `custom:mycompany`.
      - name: params
        isOptional: false
        type: UpdateCustomProviderParams
        description: The fields to update on the provider.
    examples:
      - id: update-custom-provider
        name: Update a custom provider
        isSpotlight: true
        code: |
          ```dart
          final CustomOAuthProvider provider =
              await supabase.auth.admin.customProviders.updateProvider(
            'custom:mycompany',
            UpdateCustomProviderParams(
              customClaimsAllowlist: ['groups', 'org_id', 'mail'],
            ),
          );
          ```
  - id: admin-custom-providers-delete
    title: 'admin.customProviders.deleteProvider()'
    notes: |
      Deletes a custom provider by its identifier.
    params:
      - name: identifier
        isOptional: false
        type: String
        description: The provider identifier, for example `custom:mycompany`.
    examples:
      - id: delete-custom-provider
        name: Delete a custom provider
        isSpotlight: true
        code: |
          ```dart
          await supabase.auth.admin.customProviders.deleteProvider('custom:mycompany');
          ```
  - id: functions-api
    title: 'Edge Functions'
    category: Edge Functions
  - id: invoke
    title: 'invoke()'
    description: |
      Invokes a Supabase Function. See the [guide](/docs/guides/functions) for details on writing Functions.
    notes: |
      - Requires an Authorization header.
      - Invoke params generally match the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) spec.
    params:
      - name: functionName
        isOptional: false
        type: String
        description: The name of the function to invoke.
      - name: headers
        isOptional: true
        type: Map<String, String>
        description: Custom headers to send with the request.
      - name: body
        isOptional: true
        type: Map<String, String>
        description: The body of the request.
      - name: method
        isOptional: true
        type: HttpMethod
        description: HTTP method of the request. Defaults to POST.
      - name: abortSignal
        isOptional: true
        type: Future<void>
        description: Cancels the in-flight request when the provided `Future` completes. It must not complete with an error. On abort, an `http.RequestAbortedException` (from `package:http`) is thrown. Useful for cancelling a request in response to an event or for setting a request timeout.
    examples:
      - id: basic-invocation
        name: Basic invocation.
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.functions.invoke('hello', body: {'foo': 'baa'});
          final data = res.data;
          ```
      - id: parsing-custom-headers
        name: Parsing custom headers.
        description: |
          Any `headers` will be passed through to the function. A common pattern is to pass a logged-in user's JWT token as an Authorization header.
        isSpotlight: true
        code: |
          ```dart
          final res = await supabase.functions.invoke(
            'hello',
            body: {'foo': 'baa'},
            headers: {
              'Authorization': 'Bearer ${supabase.auth.currentSession?.accessToken}'
            },
          );
          ```
      - id: aborting-a-request
        name: Aborting a request
        description: |
          Pass an `abortSignal` to cancel the in-flight request. When the `Future` completes the request is aborted and an `http.RequestAbortedException` (from `package:http`) is thrown. A `Future.delayed` gives you a per-invocation timeout.
        code: |
          ```dart
          import 'package:http/http.dart' as http;

          try {
            final res = await supabase.functions.invoke(
              'hello',
              body: {'foo': 'baa'},
              abortSignal: Future.delayed(const Duration(seconds: 5)),
            );
            final data = res.data;
          } on http.RequestAbortedException catch (error) {
            print('Request was aborted: $error');
          }
          ```
  - id: database-api
    title: 'Database'
    category: Database
  - id: select
    description: |
      Perform a SELECT query on the table or view.
    title: 'Fetch data: select()'
    notes: |
      - By default, Supabase projects will return a maximum of 1,000 rows. This setting can be changed in Project API Settings. 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/dart/using-filters)
      - `select()` can be combined with [Modifiers](/docs/reference/dart/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, separated by commas. Columns can be renamed when returned with `customName:columnName`
    examples:
      - id: getting-your-data
        name: Getting your data
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'violin'
            },
            {
              'id': 2,
              'name': 'viola'
            },
            {
              'id': 3,
              'name': 'cello'
            },
          ]
          ```
      - id: selecting-specific-columns
        name: Selecting specific columns
        description: You can select specific fields from your tables.
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('''
              name
            ''');
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'name': 'violin'
            },
            {
              'name': 'viola'
            },
            {
              'name': 'cello'
            },
          ]
          ```
      - id: query-referenced-tables
        name: Query referenced tables
        description: If your database has relationships, you can query related tables too.
        code: |
          ```dart
          final data = await supabase
            .from('orchestral_sections')
            .select('''
              name,
              instruments ( name )
            ''');
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, section_id, name)
            values
              (1, 2, 'flute'),
              (2, 1, 'violin');
            ```
        response: |
          ```json
          [
            {
              'name': 'strings',
              'instruments': [
                {
                  'name': 'violin'
                },
              ]
            },
            {
              'name': 'woodwinds',
              'instruments': [
                {
                  'name': 'flute'
                },
              ]
            },
          ]
          ```
      - id: query-referenced-tables-through-a-join-table
        name: Query referenced tables through a join table
        code: |
          ```dart
          final data = await supabase
            .from('users')
            .select('''
              name,
              teams (
                name
              )
            ''');
            ```
        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
          [
            {
              'name': 'Kiran',
              'teams': [
                {
                  'name': 'Green'
                },
                {
                  'name': 'Blue'
                },
              ]
            },
            {
              'name': 'Evan',
              'teams': [
                {
                  'name': 'Blue'
                }
              ]
            }
          ]
          ```
        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
        description: |
          Sometimes you will need to query the same referenced table twice. In
          this case, you can use the name of the joined column to identify which
          join you intend to use. For convenience, you can also give an alias
          for each column. This example queries a `messages` table that is
          joined to a `users` table via `sender_id` and `receiver_id`. Since you
          want the `name` for both sender and receiver, you can alias the
          columns as `to` and `from`.
        code: |
          ```dart
          final data = await supabase
            .from('messages')
            .select('''
              content,
              from:sender_id(name),
              to:receiver_id(name)
            ''');
          ```
        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
          [
            {
              'content': '👋',
              'from': {
                'name': 'Kiran'
              },
              'to': {
                'name': 'Evan'
              }
            }
          ]
          ```
      - id: filtering-through-referenced-tables
        name: Filtering through referenced tables
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('name, orchestral_sections(*)')
            .eq('orchestral_sections.name', 'percussion');
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, section_id, name)
            values
              (1, 2, 'flute'),
              (2, 1, 'violin');
            ```
        response: |
          ```json
          [
            {
              'name': 'flute',
              'orchestral_sections': null
            },
            {
              'name': 'violin',
              'orchestral_sections': 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-with-count-option
        name: Querying with count option
        description: |
          You can get the number of rows by using the count option.
          Allowed values for count option are [CountOption.exact](https://postgrest.org/en/stable/api.html#exact-count), [CountOptionplanned](https://postgrest.org/en/stable/api.html#planned-count) and [CountOption.estimated](https://postgrest.org/en/stable/api.html#estimated-count).
        code: |
          ```dart
          final res = await supabase
              .from('instruments')
              .select('name')
              .count(CountOption.exact);

          final data = res.data;
          final count = res.count;
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          PostgrestResponse(
            data: [
              {
                'id': 1,
                'name': 'violin'
              },
              {
                'id': 2,
                'name': 'viola'
              },
              {
                'id': 3,
                'name': 'cello'
              }
            ],
            count: 3
          );
          ```
      - id: querying-json-data
        name: Querying JSON data
        description: |
          If you have data inside of a JSONB column, you can apply select
          and query filters to the data values. Postgres offers a
          [number of operators](https://www.postgresql.org/docs/current/functions-json.html)
          for querying JSON data. Also see
          [PostgREST docs](http://postgrest.org/en/v7.0.0/api.html#json-columns) for more details.
        code: |
          ```dart
          final data = await supabase
            .from('users')
            .select('''
              id, name,
              address->city
            ''');
          ```
        data:
          sql: |
            ```sql
            create table
              users (
                id int8 primary key,
                name text,
                address jsonb
              );

            insert into
              users (id, name, address)
            values
              (1, 'Frodo', '{"city":"Hobbiton"}');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'Frodo',
              'city': 'Hobbiton'
            }
          ]
          ```
      - id: querying-referenced-table-with-inner-join
        name: Querying referenced table with inner join
        code: |
          ```dart
          final data = await supabase
            .from('orchestral_sections')
            .select('name, instruments!inner(name)')
            .eq('orchestral_sections.name', 'strings')
            .limit(1);
          ```
        data:
          sql: |
            ```sql
            create table orchestral_sections (
              "id" "uuid" primary key default "extensions"."uuid_generate_v4"() not null,
              "name" text
            );

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

            with section as (
              insert into orchestral_sections (name)
              values ('strings') returning id
            )
            insert into instruments (name, section_id) values
            ('violin', (select id from section)),
            ('viola', (select id from section)),
            ('cello', (select id from section)),
            ('double bass', (select id from section));
            ```
        response: |
          ```json
          [
            {
              'name': 'violin',
              'orchestral_sections': {'name': 'strings'}
            }
          ]
          ```
        description: |
          If you don't want to return the referenced table contents, you can leave the parenthesis empty.
          Like `.select('name, books!inner()')`.
        hideCodeBlock: true
      - id: switching-schemas-per-query
        name: Switching schemas per query
        code: |
          ```dart
          final data = await supabase
            .schema('myschema')
            .from('mytable')
            .select();
          ```
        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
          [
            {
              'id': '4162e008-27b0-4c0f-82dc-ccaeee9a624d',
              'data': 'mydata'
            }
          ]
          ```
        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
    description: |
      Perform an INSERT into the table or view.
    title: 'Create data: insert()'
    params:
      - name: values
        isOptional: false
        type: Map<String, dynamic> or List<Map<String, dynamic>>
        description: The values to insert. Pass an object to insert a single row or an array to insert multiple rows.
    examples:
      - id: create-a-record
        name: Create a record
        isSpotlight: true
        code: |
          ```dart
          await supabase
              .from('cities')
              .insert({'name': 'The Shire', 'country_id': 554});
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            ```
        hideCodeBlock: true
      - id: fetch-inserted-data
        name: Fetch inserted record
        code: |
          ```dart
          final List<Map<String, dynamic>> data =
                  await supabase.from('cities').insert([
                {'name': 'The Shire', 'country_id': 554},
                {'name': 'Rohan', 'country_id': 555},
              ]).select();
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'Denmark'
            }
          ]
          ```
      - id: bulk-create
        name: Bulk create
        code: |
          ```dart
          await supabase.from('cities').insert([
            {'name': 'The Shire', 'country_id': 554},
            {'name': 'Rohan', 'country_id': 555},
          ]);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);
            ```
        response: |
          ```json
          PostgrestException(
            'code': '23505',
            'details': 'Key (id)=(1) already exists.',
            'hint': null,
            'message': 'duplicate key value violates unique constraint "countries_pkey"'
          );
          ```

  - id: update
    description: |
      Perform an UPDATE on the table or view.
    title: 'Modify data: update()'
    notes: |
      - `update()` should always be combined with [Filters](/docs/reference/dart/using-filters) to target the item(s) you wish to update.
    params:
      - name: values
        isOptional: false
        type: Map<String, dynamic>
        description: The values to update with.
    examples:
      - id: updating-your-data
        name: Update your data
        isSpotlight: true
        code: |
          ```dart
          await supabase
            .from('instruments')
            .update({ 'name': 'piano' })
            .eq('id', 1);
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'harpsichord');
            ```
      - id: update-a-record-and-return-it
        name: Update a record and return it
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .update({ 'name': 'piano' })
            .eq('id', 1)
            .select();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'harpsichord');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'piano'
            }
          ]
          ```
        hideCodeBlock: true
      - id: updating-json-data
        name: Update JSON data
        code: |
          ```dart
          await supabase
            .from('users')
            .update({
              'address': {
                'street': 'Melrose Place',
                'postcode': 90210
              }
            })
            .eq('address->postcode', 90210);
          ```
        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
          [
            {
              'id': 1,
              'name': 'Michael',
              'address': {
                'street': 'Melrose Place',
                'postcode': 90210
              }
            }
          ]
          ```
        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.

  - id: upsert
    description: |
      Perform an UPSERT on the table or view. Depending on the column(s) passed to `onConflict`, `.upsert()` allows you to perform the equivalent of `.insert()` if a row with the corresponding `onConflict` columns doesn't exist, or if it does exist, perform an alternative action depending on `ignoreDuplicates`.
    title: 'Upsert data: upsert()'
    notes: |
      - Primary keys must be included in `values` to use upsert.
    params:
      - name: values
        isOptional: false
        type: Map<String, dynamic> or List<Map<String, dynamic>>
        description: The values to upsert with. Pass a Map to upsert a single row or an array to upsert multiple rows.
      - name: onConflict
        isOptional: true
        type: String
        description: Comma-separated UNIQUE column(s) to specify how duplicate rows are determined. Two rows are duplicates if all the `onConflict` columns are equal.
      - name: ignoreDuplicates
        isOptional: true
        type: bool
        description: If `true`, duplicate rows are ignored. If `false`, duplicate rows are merged with existing rows.
      - name: defaultToNull
        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 where ignoreDuplicates is set to false. This also only applies when doing bulk upserts.
    examples:
      - id: upsert-your-data
        name: Upsert your data
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .upsert({ 'id': 1, 'name': 'piano' })
            .select();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'harpsichord');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'piano'
            }
          ]
          ```
      - id: bulk-upsert-your-data
        name: Bulk Upsert your data
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .upsert([
              { 'id': 1, 'name': 'piano' },
              { 'id': 2, 'name': 'harp' },
            ])
            .select();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'harpsichord');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'piano'
            },
            {
              'id': 2,
              'name': 'harp'
            }
          ]
          ```
        hideCodeBlock: true
      - id: upserting-into-tables-with-constraints
        name: Upserting into tables with constraints
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('users')
            .upsert({ 'id': 42, 'handle': 'saoirse', 'display_name': 'Saoirse' }, { onConflict: 'handle' })
            .select();
          ```
        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
          PostgrestException(
            'code': '23505',
            'details': 'Key (handle)=(saoirse) already exists.',
            'hint': null,
            'message': "duplicate key value violates unique constraint "users_handle_key"'
          )
          ```
        description: |
          In the above 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 `onConflict` option, you can instruct `upsert()` to use
          another column with a unique constraint to determine conflicts.

  - id: delete
    description: |
      Perform a DELETE on the table or view.
    title: 'Delete data: delete()'
    notes: |
      - `delete()` should always be combined with [Filters](/docs/reference/dart/using-filters) to target the item(s) you wish to delete.
      - If you use `delete()` with filters and you have RLS 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.
    examples:
      - id: delete-records
        name: Delete records
        isSpotlight: true
        code: |
          ```dart
          await supabase
            .from('countries')
            .delete()
            .eq('id', 1);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Mordor');
            ```
      - id: delete-multiple-records
        name: Delete multiple records
        code: |
          ```dart
          await supabase
            .from('countries')
            .delete()
            .inFilter('id', [1, 2, 3])
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Mordor'), (2, 'Gondor'), (3, 'Rohan');
            ```
      - id: fetch-delete-records
        name: Fetch deleted records
        code: |
          ```dart
          final List<Map<String,dynamic>> data = await supabase
            .from('cities')
            .delete()
            .match({ 'id': 666 })
            .select();
          ```

  - id: rpc
    title: 'Database Functions: rpc()'
    description: |
      Perform a function call.

      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.
    params:
      - name: fn
        isOptional: false
        type: String
        description: The function name to call.
      - name: params
        isOptional: true
        type: Map<String, dynamic>
        description: The arguments to pass to the function call.
    examples:
      - id: call-a-postgres-function-without-arguments
        name: Call a Postgres function without arguments
        code: |
          ```dart
          final data = await supabase
            .rpc('hello_world');
          ```
        data:
          sql: |
            ```sql
            create function hello_world() returns text as $$
              select 'Hello world';
            $$ language sql;
            ```
        response: |
          ```json
          'Hello world'
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: call-a-postgres-function-with-arguments
        name: Call a Postgres function with arguments
        code: |
          ```dart
          final data = await supabase
            .rpc('echo_city', params: { 'say': '👋' });
          ```
        data:
          sql: |
            ```sql
            create function echo(say text) returns text as $$
              select say;
            $$ language sql;
            ```
        response: |
          ```json
          '👋'
          ```
        hideCodeBlock: true
      - id: bulk-processing
        name: Bulk processing
        code: |
          ```dart
          final data = await supabase
            .rpc('add_one_each', params: { arr: [1, 2, 3] });
          ```
        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
          [
            2,
            3,
            4,
          ]
          ```
        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: |
          ```dart
          final data = await supabase
            .rpc('list_stored_countries')
            .eq('id', 1)
            .single();
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Mordor'),
              (2, 'Gondor');

            create function list_stored_countries() returns setof countries as $$
              select * from countries;
            $$ language sql;
            ```
        response: |
          ```json
          {
            'id': 1,
            'name': 'Mordor'
          }
          ```
        description: |
          Postgres functions that return tables can also be combined with [Filters](/docs/reference/dart/using-filters) and [Modifiers](/docs/reference/dart/using-modifiers).
        hideCodeBlock: true

  - id: realtime-api
    title: 'Realtime'
    category: Realtime
  - id: subscribe
    description: |
      Subscribe to realtime changes in your database.
    title: 'on().subscribe()'
    notes: |
      - Realtime is disabled by default for new tables. You can turn it on by [managing replication](/docs/guides/realtime/postgres-changes#replication-setup).
      - If you want to receive the "previous" data for updates and deletes, you will need to set `REPLICA IDENTITY` to `FULL`, like this: `ALTER TABLE your_table REPLICA IDENTITY FULL;`
    examples:
      - id: listen-to-database-changes
        name: Listen to database changes
        isSpotlight: true
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.all,
                  schema: 'public',
                  table: 'countries',
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-to-inserts
        name: Listen to inserts
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.insert,
                  schema: 'public',
                  table: 'countries',
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-to-updates
        name: Listen to updates
        description: |
          By default, Supabase will send only the updated record. If you want to receive the previous values as well you can
          enable full replication for the table you are listening too:

          ```sql
          alter table "your_table" replica identity full;
          ```
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.update,
                  schema: 'public',
                  table: 'countries',
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-to-deletes
        name: Listen to deletes
        description: |
          By default, Supabase does not send deleted records. If you want to receive the deleted record you can
          enable full replication for the table you are listening too:

          ```sql
          alter table "your_table" replica identity full;
          ```
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.delete,
                  schema: 'public',
                  table: 'countries',
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-to-multiple-events
        name: Listen to multiple events
        description: You can chain listeners if you want to listen to multiple events for each table.
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.insert,
                  schema: 'public',
                  table: 'countries',
                  callback: (payload) {
                    print('Insert event received: ${payload.toString()}');
                  })
              .onPostgresChanges(
                  event: PostgresChangeEvent.delete,
                  schema: 'public',
                  table: 'countries',
                  callback: (payload) {
                    print('Delete event received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listening-to-row-level-changes
        name: Listen to row level changes
        description: You can listen to individual rows by using the `filter` parameter passing a `PostgresChangeFilter` object with `PostgresChangeFilterType.eq` as `type`.
        code: |
          ```dart
          supabase
              .channel('public:countries:id=eq.200')
              .onPostgresChanges(
                  event: PostgresChangeEvent.delete,
                  schema: 'public',
                  table: 'countries',
                  filter: PostgresChangeFilter(
                    type: PostgresChangeFilterType.eq,
                    column: 'id',
                    value: 200,
                  ),
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-with-pattern-and-negated-filters
        name: Listen with pattern and negated filters
        description: |
          Besides equality, `PostgresChangeFilterType` supports `neq`, `lt`, `lte`, `gt`, `gte`, `inFilter`, `like`, `ilike`, `isFilter`, `match`, `imatch`, and `isDistinct`. Set `negate: true` to prefix the operator with `not.`.
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.all,
                  schema: 'public',
                  table: 'countries',
                  filter: PostgresChangeFilter(
                    type: PostgresChangeFilterType.ilike,
                    column: 'name',
                    value: '%land%',
                    negate: true,
                  ),
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-with-multiple-filters
        name: Listen with multiple filters
        description: Pass a list of filters to `filters` to combine several conditions with `AND`. Use `select` to limit the change payload to a subset of columns.
        code: |
          ```dart
          supabase
              .channel('public:countries')
              .onPostgresChanges(
                  event: PostgresChangeEvent.update,
                  schema: 'public',
                  table: 'countries',
                  filters: [
                    PostgresChangeFilter(
                      type: PostgresChangeFilterType.gte,
                      column: 'population',
                      value: 1000000,
                    ),
                    PostgresChangeFilter(
                      type: PostgresChangeFilterType.eq,
                      column: 'continent',
                      value: 'Europe',
                    ),
                  ],
                  select: ['id', 'name', 'population'],
                  callback: (payload) {
                    print('Change received: ${payload.toString()}');
                  })
              .subscribe();
          ```
      - id: listen-to-broadcast
        name: Listen to broadcast messages
        code: |
          ```dart
          supabase
              .channel('room1')
              .onBroadcast(
                  event: 'cursor-pos',
                  callback: (payload) {
                    print('Cursor position received!: $payload');
                  })
              .subscribe();
          ```
      - id: listen-to-presence-events
        name: Listen to presence events
        code: |
          ```dart
          final channel = supabase.channel('room1');

          channel.onPresenceSync((payload) {
            print('Synced presence state: ${channel.presenceState()}');
          }).onPresenceJoin((payload) {
            print('Newly joined presences $payload');
          }).onPresenceLeave((payload) {
            print('Newly left presences: $payload');
          }).subscribe((status, error) async {
            if (status == RealtimeSubscribeStatus.subscribed) {
              await channel.track({'online_at': DateTime.now().toIso8601String()});
            }
          });
          ```
  - id: remove-channel
    description: |
      Unsubscribes and removes Realtime channel from Realtime client.
    title: 'removeChannel()'
    notes: |
      - Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
    examples:
      - id: removes-a-channel
        name: Remove a channel
        isSpotlight: true
        code: |
          ```dart
          final status = await supabase.removeChannel(channel);
          ```

  - id: remove-all-channels
    description: |
      Unsubscribes and removes all Realtime channels from Realtime client.
    title: 'removeAllChannels()'
    notes: |
      - Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
    examples:
      - id: remove-all-channels
        name: Remove all channels
        isSpotlight: true
        code: |
          ```dart
          final statuses = await supabase.removeAllChannels();
          ```

  - id: get-channels
    description: |
      Returns all Realtime channels.
    title: 'getChannels()'
    examples:
      - id: get-all-channels
        name: Get all channels
        isSpotlight: true
        code: |
          ```dart
          final channels = supabase.getChannels();
          ```

  - id: on-heartbeat
    description: |
      A `Stream` that emits a status every time the Realtime client sends a heartbeat, receives an acknowledgement, or when a heartbeat goes unanswered.
    title: 'onHeartbeat()'
    notes: |
      - Each event is a `RealtimeHeartbeatStatus`: `sent` when a heartbeat is pushed, `ok` or `error` when the server acknowledges it, and `timeout` when a prior heartbeat is not answered in time.
      - Useful for observing connection health, for example to surface a reconnecting indicator in your UI.
    examples:
      - id: listen-to-heartbeat
        name: Listen to heartbeat status
        isSpotlight: true
        code: |
          ```dart
          final subscription = supabase.realtime.onHeartbeat.listen((status) {
            print('Heartbeat status: $status');
          });
          ```

  - id: stream
    description: |
      Returns real-time data from your table as a `Stream`.
    title: 'stream()'
    notes: |
      - Realtime is disabled by default for new tables. You can turn it on by [managing replication](/docs/guides/realtime/postgres-changes#replication-setup).
      - `stream()` will emit the initial data as well as any further change on the database as `Stream<List<Map<String, dynamic>>>` by combining Postgrest and Realtime.
      - Takes a list of primary key column names that will be used to update and delete the proper records within the SDK.
      - To use a private Realtime channel, pass `channelOptions: const RealtimeChannelConfig(private: true)` to the `stream()` call.
      - The following filters are available
        - `.eq('column', value)` listens to rows where the column equals the value
        - `.neq('column', value)` listens to rows where the column does not equal the value
        - `.gt('column', value)` listens to rows where the column is greater than the value
        - `.gte('column', value)` listens to rows where the column is greater than or equal to the value
        - `.lt('column', value)` listens to rows where the column is less than the value
        - `.lte('column', value)` listens to rows where the column is less than or equal to the value
        - `.inFilter('column', [val1, val2, val3])` listens to rows where the column is one of the values
    examples:
      - id: listen-to-table
        name: Listen to a table
        isSpotlight: true
        code: |
          ```dart
          supabase.from('countries')
            .stream(primaryKey: ['id'])
            .listen((List<Map<String, dynamic>> data) {
            // Do something awesome with the data
          });
          ```
      - id: with-filter-order-limit
        name: With filter, order and limit
        code: |
          ```dart
          supabase.from('countries')
            .stream(primaryKey: ['id'])
            .eq('id', 120)
            .order('name')
            .limit(10);
          ```
      - id: with-in-filter
        name: With an IN filter
        code: |
          ```dart
          supabase.from('countries')
            .stream(primaryKey: ['id'])
            .inFilter('id', [1, 2, 3])
            .order('name')
            .limit(10);
          ```
      - id: using-stream-with-stream-builder
        name: Using `stream()` with `StreamBuilder`
        description: |
          When using `stream()` with a `StreamBuilder` within your Flutter application, make sure to store your stream in a variable to prevent refetching upon rebuilding.
        code: |
          ```dart
          final supabase = Supabase.instance.client;

          class MyWidget extends StatefulWidget {
            const MyWidget({Key? key}) : super(key: key);

            @override
            State<MyWidget> createState() => _MyWidgetState();
          }

          class _MyWidgetState extends State<MyWidget> {
            // Persist the stream in a local variable to prevent refetching upon rebuilds
            final _stream = supabase.from('countries').stream(primaryKey: ['id']);

            @override
            Widget build(BuildContext context) {
              return StreamBuilder(
                stream: _stream,
                builder: (context, snapshot) {
                  // Return your widget with the data from the snapshot
                },
              );
            }
          }
          ```
  - id: file-buckets
    title: 'Overview'
    category: Storage
    subcategory: File Buckets
    notes: |
      This section contains methods for working with File Buckets.

  - id: list-buckets
    description: |
      Retrieves the details of all Storage buckets within an existing product.
    title: 'listBuckets()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `select`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: options
        isOptional: true
        type: ListBucketsOptions
        description: Optionally filter, sort and paginate the returned buckets. Calling `listBuckets()` without any options returns all buckets.
        subContent:
          - name: limit
            isOptional: true
            type: int
            description: The maximum number of buckets to return.
          - name: offset
            isOptional: true
            type: int
            description: The number of buckets to skip.
          - name: search
            isOptional: true
            type: String
            description: A search term used to filter buckets by name.
          - name: sortColumn
            isOptional: true
            type: BucketSortColumn
            description: The column to sort the buckets by. One of `BucketSortColumn.id`, `BucketSortColumn.name`, `BucketSortColumn.createdAt` or `BucketSortColumn.updatedAt`.
          - name: sortOrder
            isOptional: true
            type: BucketSortOrder
            description: The direction to sort the buckets in. Either `BucketSortOrder.ascending` or `BucketSortOrder.descending`.
    examples:
      - id: list-buckets
        name: List buckets
        isSpotlight: true
        code: |
          ```dart
          final List<Bucket> buckets = await supabase
            .storage
            .listBuckets();
          ```
        response: |
          ```json
          [
            Bucket(
              id: 'avatars',
              name: 'avatars',
              owner: '',
              public: false,
              file_size_limit: 1024,
              allowed_mime_types: [
                'image/png'
              ],
              created_at: '2024-05-22T22:26:05.100Z',
              updated_at: '2024-05-22T22:26:05.100Z'
            ),
          ]
          ```
      - id: list-buckets-with-options
        name: With filter, sort and pagination
        code: |
          ```dart
          final List<Bucket> buckets = await supabase
            .storage
            .listBuckets(
              const ListBucketsOptions(
                limit: 10,
                offset: 0,
                search: 'avatar',
                sortColumn: BucketSortColumn.createdAt,
                sortOrder: BucketSortOrder.descending,
              ),
            );
          ```

  - id: get-bucket
    description: |
      Retrieves the details of an existing Storage bucket.
    title: 'getBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `select`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: The unique identifier of the bucket you would like to retrieve.
    examples:
      - id: get-bucket
        name: Get bucket
        isSpotlight: true
        code: |
          ```dart
          final Bucket bucket = await supabase
            .storage
            .getBucket('avatars');
          ```
        response: |
          ```json
          Bucket(
            id: 'avatars',
            name: 'avatars',
            owner: '',
            public: false,
            file_size_limit: 1024,
            allowed_mime_types: [
              'image/png'
            ],
            created_at: '2024-05-22T22:26:05.100Z',
            updated_at: '2024-05-22T22:26:05.100Z'
          )
          ```
  - id: create-bucket
    description: |
      Creates a new Storage bucket
    title: 'createBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `insert`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: A unique identifier for the bucket you are creating.
      - name: bucketOptions
        isOptional: true
        type: BucketOptions
        description: A parameter to optionally make the bucket public.
        subContent:
          - name: public
            isOptional: false
            type: bool
            description: The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private.
          - name: fileSizeLimit
            isOptional: true
            type: String
            description: Specifies the max file size in bytes that can be uploaded to this bucket. The global file size limit takes precedence over this value. The default value is null, which doesn't set a per bucket file size limit.
          - name: allowedMimeTypes
            isOptional: true
            type: List<String>
            description: Specifies the allowed mime types that this bucket can accept during upload. The default value is null, which allows files with all mime types to be uploaded. Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
    examples:
      - id: create-bucket
        name: Create bucket
        isSpotlight: true
        code: |
          ```dart
          final String bucketId = await supabase
            .storage
            .createBucket('avatars');
          ```
        response: |
          ```json
          'avatars'
          ```

  - id: empty-bucket
    description: |
      Removes all objects inside a single bucket.
    title: 'emptyBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `select`
        - `objects` permissions: `select` and `delete`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: A unique identifier for the bucket you are emptying.
    examples:
      - id: empty-bucket
        name: Empty bucket
        isSpotlight: true
        code: |
          ```dart
          final String res = await supabase
            .storage
            .emptyBucket('avatars');
          ```
        response: |
          ```json
          'Successfully emptied'
          ```
  - id: update-bucket
    description: |
      Updates a new Storage bucket
    title: 'updateBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `update`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: A unique identifier for the bucket you are updating.
      - name: bucketOptions
        isOptional: false
        type: BucketOptions
        description: A parameter to optionally make the bucket public.
        subContent:
          - name: public
            isOptional: false
            type: bool
            description: The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private.
          - name: fileSizeLimit
            isOptional: true
            type: String
            description: Specifies the max file size in bytes that can be uploaded to this bucket. The global file size limit takes precedence over this value. The default value is null, which doesn't set a per bucket file size limit.
          - name: allowedMimeTypes
            isOptional: true
            type: List<String>
            description: Specifies the allowed mime types that this bucket can accept during upload. The default value is null, which allows files with all mime types to be uploaded. Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
    examples:
      - id: update-bucket
        name: Update bucket
        isSpotlight: true
        code: |
          ```dart
          final String res = await supabase
            .storage
            .updateBucket('avatars', const BucketOptions(public: false));
          ```
        response: |
          ```json
          'Successfully updated'
          ```

  - id: delete-bucket
    description: |
      Deletes an existing bucket. A bucket can't be deleted with existing objects inside it. You must first `empty()` the bucket.
    title: 'deleteBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `select` and `delete`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: A unique identifier for the bucket you are deleting.
    examples:
      - id: delete-bucket
        name: Delete bucket
        isSpotlight: true
        code: |
          ```dart
          final String res = await supabase
            .storage
            .deleteBucket('avatars');
          ```
        response: |
          ```json
          'Successfully deleted'
          ```

  - id: purge-bucket-cache
    description: |
      Invalidates the CDN cache for every object in a bucket.
    title: 'purgeBucketCache()'
    notes: |
      - Requires the `secret` key and the `purgeCache` feature enabled for your project on the storage server.
      - When `transformations` is `true`, only the resized/formatted variants are purged, leaving the original cached objects intact. Otherwise the bucket's object cache is purged.
      - Policy permissions required:
        - `buckets` permissions: `select`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: The unique identifier of the bucket whose CDN cache should be purged.
      - name: transformations
        isOptional: true
        type: bool
        description: When true, only the transformed (resized/formatted) variants are purged, leaving the original cached objects intact. Defaults to false.
    examples:
      - id: purge-bucket-cache
        name: Purge the CDN cache for a bucket
        isSpotlight: true
        code: |
          ```dart
          final String res = await supabase
            .storage
            .purgeBucketCache('avatars');
          ```

  - id: from-upload
    description: |
      Uploads a file to an existing bucket.
    title: 'from.upload()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `insert`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The relative file path. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to update.
      - name: file
        isOptional: false
        type: File or Uint8List
        description: File object to be stored in the bucket.
      - name: fileOptions
        isOptional: true
        type: FileOptions
        subContent:
          - name: cacheControl
            isOptional: true
            type: String
            description: The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control` header as `max-age=<seconds>`. Defaults to 3600 seconds.
          - name: upsert
            isOptional: true
            type: bool
            description: When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false.
          - name: contentType
            isOptional: true
            type: String
            description: The `Content-Type` header value. Gets parsed with MediaType.parse(mime). Throws a FormatError if the media type is invalid.
      - name: retryAttempts
        isOptional: true
        type: int
        description: Sets the retryAttempts parameter set across the storage client. Defaults to 10.
      - name: retryController
        isOptional: true
        type: StorageRetryController
        description: Pass a RetryController instance and call `cancel()` to cancel the retry attempts.
    examples:
      - id: upload-file
        name: Upload file
        isSpotlight: true
        code: |
          ```dart
          final avatarFile = File('path/to/file');
          final String fullPath = await supabase.storage.from('avatars').upload(
                'public/avatar1.png',
                avatarFile,
                fileOptions: const FileOptions(cacheControl: '3600', upsert: false),
              );
          ```
        response: |
          ```json
          'avatars/public/avatar1.png'
          ```
      - id: upload-file-on-web
        name: Upload file on web
        code: |
          ```dart
          final Uint8List avatarFile = file.bytes;
          final String fullPath = await supabase.storage.from('avatars').uploadBinary(
                'public/avatar1.png',
                avatarFile,
                fileOptions: const FileOptions(cacheControl: '3600', upsert: false),
              );
          ```
        response: |
          ```json
          'avatars/public/avatar1.png'
          ```

  - id: from-update
    description: |
      Replaces an existing file at the specified path with a new one.
    title: 'from.update()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `update` and `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The relative file path. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to update.
      - name: file
        isOptional: false
        type: File or Uint8List
        description: File object to be stored in the bucket.
      - name: fileOptions
        isOptional: true
        type: FileOptions
        subContent:
          - name: cacheControl
            isOptional: true
            type: String
            description: The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control` header as `max-age=<seconds>`. Defaults to 3600 seconds.
          - name: upsert
            isOptional: true
            type: bool
            description: When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false.
          - name: contentType
            isOptional: true
            type: String
            description: The `Content-Type` header value. Gets parsed with MediaType.parse(mime). Throws a FormatError if the media type is invalid.
      - name: retryAttempts
        isOptional: true
        type: int
        description: Sets the retryAttempts parameter set across the storage client. Defaults to 10.
      - name: retryController
        isOptional: true
        type: StorageRetryController
        description: Pass a RetryController instance and call `cancel()` to cancel the retry attempts.
    examples:
      - id: update-file
        name: Update file
        isSpotlight: true
        code: |
          ```dart
          final avatarFile = File('path/to/local/file');
          final String path = await supabase.storage.from('avatars').update(
                'public/avatar1.png',
                avatarFile,
                fileOptions: const FileOptions(cacheControl: '3600', upsert: false),
              );
          ```
        response: |
          ```json
          'avatars/public/avatar1.png'
          ```
      - id: update-file-on-web
        name: Update file on web
        code: |
          ```dart
          final Uint8List avatarFile = file.bytes;
          final String path = await supabase.storage.from('avatars').updateBinary(
                'public/avatar1.png',
                avatarFile,
                fileOptions: const FileOptions(cacheControl: '3600', upsert: false),
              );
          ```
        response: |
          ```json
          'avatars/public/avatar1.png'
          ```

  - id: from-move
    description: |
      Moves an existing file, optionally renaming it at the same time.
    title: 'from.move()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `update` and `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: fromPath
        isOptional: false
        type: String
        description: The original file path, including the current file name. For example folder/image.png.
      - name: toPath
        isOptional: false
        type: String
        description: The new file path, including the new file name. For example folder/image-new.png.
    examples:
      - id: move-file
        name: Move file
        isSpotlight: true
        code: |
          ```dart
          final String result = await supabase
            .storage
            .from('avatars')
            .move('public/avatar1.png', 'private/avatar2.png');
          ```
        response: |
          ```json
          'Successfully moved'
          ```

  - id: from-create-signed-url
    description: |
      Create signed url to download file without requiring permissions. This URL can be valid for a set number of seconds.
    title: 'from.createSignedUrl()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The file path, including the file name. For example folder/image.png.
      - name: expiresIn
        isOptional: false
        type: int
        description: The number of seconds until the signed URL expires. For example, 60 for a URL which is valid for one minute.
      - name: download
        isOptional: true
        type: DownloadBehavior
        description: Triggers the file to be downloaded rather than opened in the browser. Use `DownloadBehavior.withOriginalName` to keep the original file name or `DownloadBehavior.named('custom.png')` to override it.
      - name: cacheNonce
        isOptional: true
        type: String
        description: Appends a `cacheNonce` query parameter to the signed URL to bypass CDN caching for a specific file version.
      - name: transform
        isOptional: true
        type: TransformOptions
        description: Transform the asset before serving it to the client.
        subContent:
          - name: width
            isOptional: true
            type: int
            description: The width of the image in pixels.
          - name: height
            isOptional: true
            type: int
            description: The height of the image in pixels.
          - name: resize
            isOptional: true
            type: ResizeMode
            description: Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`.
          - name: quality
            isOptional: true
            type: int
            description: Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80
          - name: format
            isOptional: true
            type: RequestImageFormat
            description: Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp.
    examples:
      - id: create-signed-url
        name: Create Signed URL
        isSpotlight: true
        code: |
          ```dart
          final String signedUrl = await supabase
            .storage
            .from('avatars')
            .createSignedUrl('avatar1.png', 60);
          ```
      - id: create-signed-url-with-transform
        name: With transform
        code: |
          ```dart
          final String signedUrl = await supabase
            .storage
            .from('avatars')
            .createSignedUrl(
              'avatar1.png',
              60,
              transform: TransformOptions(
                width: 200,
                height: 200,
              ),
            );
          ```
        response: |
          ```json
          'https://example.supabase.co/storage/v1/object/sign/avatars/folder/avatar1.png?token=<TOKEN>''
          ```
      - id: create-signed-url-with-download
        name: With download
        code: |
          ```dart
          final String signedUrl = await supabase
            .storage
            .from('avatars')
            .createSignedUrl(
              'avatar1.png',
              60,
              download: DownloadBehavior.withOriginalName,
            );
          ```
      - id: create-signed-url-with-cache-nonce
        name: Bypass the CDN cache
        code: |
          ```dart
          final String signedUrl = await supabase
            .storage
            .from('avatars')
            .createSignedUrl(
              'avatar1.png',
              60,
              cacheNonce: 'v2',
            );
          ```

  - id: from-create-signed-upload-url
    description: |
      Creates a signed upload URL. Signed upload URLs can be used to upload files to a bucket without further authentication. They are valid for 2 hours.
    title: 'from.createSignedUploadUrl()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `insert`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The file path, including the current file name. For example folder/image.png.
      - name: upsert
        isOptional: true
        type: bool
        description: If true, the signed URL allows overwriting an existing file at the path. Defaults to false.
    examples:
      - id: create-signed-upload-url
        name: Create signed upload URL
        isSpotlight: true
        code: |
          ```dart
          final response = await supabase
            .storage
            .from('avatars')
            .createSignedUploadUrl('folder/avatar1.png');
          ```
      - id: create-signed-upload-url-with-upsert
        name: With upsert
        code: |
          ```dart
          final response = await supabase
            .storage
            .from('avatars')
            .createSignedUploadUrl(
              'folder/avatar1.png',
              upsert: true,
            );
          ```

  - id: from-get-public-url
    description: |
      Retrieve URLs for assets in public buckets
    title: 'from.getPublicUrl()'
    notes: |
      - The bucket needs to be set to public, either via [updateBucket()](/docs/reference/dart/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"
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The path and name of the file to generate the public URL for. For example folder/image.png.
      - name: download
        isOptional: true
        type: DownloadBehavior
        description: Triggers the file to be downloaded rather than opened in the browser. Use `DownloadBehavior.withOriginalName` to keep the original file name or `DownloadBehavior.named('custom.png')` to override it.
      - name: cacheNonce
        isOptional: true
        type: String
        description: Appends a `cacheNonce` query parameter to the URL to bypass CDN caching for a specific file version.
      - name: transform
        isOptional: true
        type: TransformOptions
        description: Transform the asset before serving it to the client.
        subContent:
          - name: width
            isOptional: true
            type: int
            description: The width of the image in pixels.
          - name: height
            isOptional: true
            type: int
            description: The height of the image in pixels.
          - name: resize
            isOptional: true
            type: ResizeMode
            description: Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`.
          - name: quality
            isOptional: true
            type: int
            description: Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80
          - name: format
            isOptional: true
            type: RequestImageFormat
            description: Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp.
    examples:
      - id: returns-the-url-for-an-asset-in-a-public-bucket
        name: Returns the URL for an asset in a public bucket
        isSpotlight: true
        code: |
          ```dart
          final String publicUrl = supabase
            .storage
            .from('public-bucket')
            .getPublicUrl('avatar1.png');
          ```
        response: |
          ```json
          'https://example.supabase.co/storage/v1/object/public/public-bucket/folder/avatar1.png'
          ```
      - id: returns-the-url-for-an-asset-in-a-public-bucket-with-transform
        name: With transform
        isSpotlight: true
        code: |
          ```dart
          final String publicUrl = await supabase
            .storage
            .from('public-bucket')
            .getPublicUrl(
              'avatar1.png',
              transform: TransformOptions(
                width: 200,
                height: 200,
              ),
            );
          ```
        response: |
          ```json
          'https://example.supabase.co/storage/v1/object/public/public-bucket/folder/avatar1.png'
          ```
      - id: returns-the-url-for-an-asset-with-download
        name: Trigger download
        code: |
          ```dart
          final String publicUrl = supabase
            .storage
            .from('public-bucket')
            .getPublicUrl(
              'avatar1.png',
              download: DownloadBehavior.withOriginalName,
            );
          ```
      - id: returns-the-url-for-an-asset-with-cache-nonce
        name: Bypass the CDN cache
        code: |
          ```dart
          final String publicUrl = supabase
            .storage
            .from('public-bucket')
            .getPublicUrl(
              'avatar1.png',
              cacheNonce: 'v2',
            );
          ```
        response: |
          ```json
          'https://example.supabase.co/storage/v1/object/public/public-bucket/avatar1.png?cacheNonce=v2'
          ```

  - id: from-download
    description: |
      Downloads a file.
    title: 'from.download()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The full path and file name of the file to be downloaded. For example folder/image.png.
      - name: cacheNonce
        isOptional: true
        type: String
        description: Adds a `cacheNonce` query parameter to bypass CDN caching for a specific file version.
      - name: transform
        isOptional: true
        type: TransformOptions
        description: Transform the asset before serving it to the client.
        subContent:
          - name: width
            isOptional: true
            type: int
            description: The width of the image in pixels.
          - name: height
            isOptional: true
            type: int
            description: The height of the image in pixels.
          - name: resize
            isOptional: true
            type: ResizeMode
            description: Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`.
          - name: quality
            isOptional: true
            type: int
            description: Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80
          - name: format
            isOptional: true
            type: RequestImageFormat
            description: Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp.
    examples:
      - id: download-file
        name: Download file
        isSpotlight: true
        code: |
          ```dart
          final Uint8List file = await supabase
            .storage
            .from('avatars')
            .download('avatar1.png');
          ```
        response: |
          ```json
          <Blob>
          ```
      - id: download-file-with-transform
        name: With transform
        isSpotlight: true
        code: |
          ```dart
          final Uint8List file = await supabase
            .storage
            .from('avatars')
            .download(
              'avatar1.png',
              transform: TransformOptions(
                width: 200,
                height: 200,
              ),
            );
          ```
        response: |
          ```json
          <Blob>
          ```
      - id: download-file-with-cache-nonce
        name: Bypass the CDN cache
        code: |
          ```dart
          final Uint8List file = await supabase
            .storage
            .from('avatars')
            .download(
              'avatar1.png',
              cacheNonce: 'v2',
            );
          ```
        response: |
          ```json
          <Blob>
          ```

  - id: from-download-stream
    description: |
      Downloads a file as a lazy `Stream<Uint8List>`, streaming the bytes instead of buffering the whole file into memory like `download()`.
    title: 'from.downloadStream()'
    notes: |
      - The request is sent when the stream is listened to. A non-success response surfaces as a `StorageException` on the stream before any bytes are emitted.
      - Prefer this over [`download()`](/docs/reference/dart/storage-from-download) for large files to keep memory usage low.
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The full path and file name of the file to be downloaded. For example folder/image.png.
      - name: cacheNonce
        isOptional: true
        type: String
        description: Adds a `cacheNonce` query parameter to bypass CDN caching for a specific file version.
      - name: transform
        isOptional: true
        type: TransformOptions
        description: Transform the asset before serving it to the client.
        subContent:
          - name: width
            isOptional: true
            type: int
            description: The width of the image in pixels.
          - name: height
            isOptional: true
            type: int
            description: The height of the image in pixels.
          - name: resize
            isOptional: true
            type: ResizeMode
            description: Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`.
          - name: quality
            isOptional: true
            type: int
            description: Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80
          - name: format
            isOptional: true
            type: RequestImageFormat
            description: Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp.
    examples:
      - id: download-file-as-stream
        name: Download a file as a stream
        isSpotlight: true
        code: |
          ```dart
          final Stream<Uint8List> stream = supabase
            .storage
            .from('avatars')
            .downloadStream('avatar1.png');

          await for (final chunk in stream) {
            // Handle each chunk of bytes as it arrives
          }
          ```

  - id: from-purge-cache
    description: |
      Invalidates the CDN cache for a single object in a bucket.
    title: 'from.purgeCache()'
    notes: |
      - Requires the `secret` key and the `purgeCache` feature enabled for your project on the storage server.
      - When `transformations` is `true`, only the resized/formatted variants are purged, leaving the original cached object intact. Otherwise the object's cache is purged.
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The path and name of the object to purge from the CDN cache. For example folder/image.png.
      - name: transformations
        isOptional: true
        type: bool
        description: When true, only the transformed (resized/formatted) variants are purged, leaving the original cached object intact. Defaults to false.
    examples:
      - id: purge-object-cache
        name: Purge the CDN cache for an object
        isSpotlight: true
        code: |
          ```dart
          final String res = await supabase
            .storage
            .from('avatars')
            .purgeCache('avatar1.png');
          ```
      - id: purge-object-transformations-cache
        name: Purge only the transformed variants
        code: |
          ```dart
          final String res = await supabase
            .storage
            .from('avatars')
            .purgeCache('avatar1.png', transformations: true);
          ```

  - id: from-remove
    description: |
      Deletes files within the same bucket
    title: 'from.remove()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `delete` and `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: paths
        isOptional: false
        type: List<String>
        description: A list of files to delete, including the path and file name. For example ['folder/image.png'].
    examples:
      - id: delete-file
        name: Delete file
        isSpotlight: true
        code: |
          ```dart
          final List<FileObject> objects = await supabase
            .storage
            .from('avatars')
            .remove(['avatar1.png']);
          ```
        response: |
          ```json
          [
            FileObject(
            name: 'avatar1.png',
            id: 'e668cf7f-821b-4a2f-9dce-7dfa5dd1cfd2',
            updated_at: '2024-05-22T23:06:05.580Z',
            created_at: '2024-05-22T23:04:34.443Z',
            last_accessed_at: '2024-05-22T23:04:34.443Z',
            metadata: {
              eTag: 'c5e8c553235d9af30ef4f6e280790b92',
              size: 32175,
              mimetype: 'image/png',
              cacheControl: 'max-age=3600',
              lastModified: '2024-05-22T23:06:05.574Z',
              contentLength: 32175,
              httpStatusCode: 200
            ),
          ]
          ```

  - id: from-list
    description: |
      Lists all the files within a bucket.
    title: 'from.list()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: path
        isOptional: false
        type: String
        description: The folder path.
      - name: searchOptions
        isOptional: true
        type: SearchOptions
        description: Options for the search operations such as limit and offset.
        subContent:
          - name: limit
            isOptional: true
            type: int
            description: The number of files you want to be returned.
          - name: offset
            isOptional: true
            type: int
            description: The starting position.
          - name: sortBy
            isOptional: true
            type: SortBy
            description: The column to sort by. Can be any column inside a FileObject.
            subContent:
              - name: column
                isOptional: true
                type: String
              - name: order
                isOptional: true
                type: String
          - name: search
            isOptional: true
            type: String
            description: The search string to filter files by.
    examples:
      - id: list-files-in-a-bucket
        name: List files in a bucket
        isSpotlight: true
        code: |
          ```dart
          final List<FileObject> objects = await supabase
            .storage
            .from('avatars')
            .list();
          ```
        response: |
          ```json
          [
            FileObject(
            name: 'avatar1.png',
            id: 'e668cf7f-821b-4a2f-9dce-7dfa5dd1cfd2',
            updated_at: '2024-05-22T23:06:05.580Z',
            created_at: '2024-05-22T23:04:34.443Z',
            last_accessed_at: '2024-05-22T23:04:34.443Z',
            metadata: {
              eTag: 'c5e8c553235d9af30ef4f6e280790b92',
              size: 32175,
              mimetype: 'image/png',
              cacheControl: 'max-age=3600',
              lastModified: '2024-05-22T23:06:05.574Z',
              contentLength: 32175,
              httpStatusCode: 200
            ),
          ]
          ```
  - id: storagefile-list-v2
    description: |
      Lists files and folders within a bucket with cursor-based pagination and hierarchical (delimiter) listing.
    title: 'from.listPaginated()'
    notes: |
      - Folder entries in `PaginatedListResult.folders` only contain a name (and optionally a key). Full metadata is only available on the file entries in `PaginatedListResult.objects`.
      - To fetch the next page, pass the `PaginatedListResult.nextCursor` value from the previous request as `PaginatedSearchOptions.cursor`. Use `PaginatedListResult.hasNext` to check whether more results are available.
      - Policy permissions required:
        - `buckets` permissions: none
        - `objects` permissions: `select`
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: options
        isOptional: true
        type: PaginatedSearchOptions
        description: Options for the paginated search operation.
        subContent:
          - name: limit
            isOptional: true
            type: int
            description: The number of files to return. Defaults to 1000 on the server when omitted.
          - name: prefix
            isOptional: true
            type: String
            description: The prefix to filter files by.
          - name: cursor
            isOptional: true
            type: String
            description: The cursor used for pagination. Pass the `PaginatedListResult.nextCursor` value from the previous request to fetch the next page.
          - name: withDelimiter
            isOptional: true
            type: bool
            description: Whether to emulate a hierarchical listing of objects using delimiters. When `false` (default) all objects are listed as a flat list. When `true` the response groups objects by delimiter, separating them into `PaginatedListResult.folders` and `PaginatedListResult.objects`.
          - name: sortBy
            isOptional: true
            type: FileSort
            description: The column and direction to sort by.
            subContent:
              - name: column
                isOptional: true
                type: FileSortColumn
                description: The column to sort by. One of `FileSortColumn.name`, `FileSortColumn.updatedAt` or `FileSortColumn.createdAt`. Defaults to `FileSortColumn.name`.
              - name: order
                isOptional: true
                type: FileSortOrder
                description: The sort direction. Either `FileSortOrder.ascending` or `FileSortOrder.descending`. Defaults to `FileSortOrder.ascending`.
    examples:
      - id: list-files-paginated
        name: List files with pagination
        isSpotlight: true
        code: |
          ```dart
          final PaginatedListResult result = await supabase
            .storage
            .from('avatars')
            .listPaginated(
              options: const PaginatedSearchOptions(
                prefix: 'folder/',
                limit: 100,
                withDelimiter: true,
                sortBy: FileSort(
                  column: FileSortColumn.createdAt,
                  order: FileSortOrder.descending,
                ),
              ),
            );

          for (final folder in result.folders) {
            // Handle each folder
          }
          for (final object in result.objects) {
            // Handle each file
          }
          ```
      - id: list-files-paginated-next-page
        name: Fetch the next page
        code: |
          ```dart
          var result = await supabase
            .storage
            .from('avatars')
            .listPaginated();

          while (result.hasNext) {
            result = await supabase
              .storage
              .from('avatars')
              .listPaginated(
                options: PaginatedSearchOptions(cursor: result.nextCursor),
              );
          }
          ```
  - id: analytics-buckets
    title: 'Overview'
    category: Storage
    subcategory: Analytics Buckets
    notes: |
      This section contains methods for working with Analytics Buckets.
  - id: storageanalytics-from
    description: |
      Returns an Iceberg REST Catalog client for an analytics bucket, used to manage the namespaces and tables (the warehouse) inside it.
    title: 'storage.analyticsCatalog()'
    notes: |
      - Analytics buckets are backed by the Apache Iceberg table format.
      - `analyticsCatalog()` returns an `IcebergRestCatalog` scoped to a single analytics bucket. Use it to create and manage namespaces and tables within that bucket.
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: bucketId
        isOptional: false
        type: String
        description: The identifier of the analytics bucket (the warehouse) whose namespaces and tables you want to manage.
      - name: accessDelegation
        isOptional: true
        type: List<AccessDelegation>
        description: Requests server side access delegation for the catalog operations.
    examples:
      - id: get-analytics-catalog
        name: Get an analytics catalog client
        isSpotlight: true
        code: |
          ```dart
          final catalog = supabase
            .storage
            .analyticsCatalog('my-analytics-bucket');

          await catalog.createNamespace(['analytics']);
          ```
  - id: storageanalytics-createbucket
    description: |
      Creates a new analytics bucket backed by the Apache Iceberg table format.
    title: 'createAnalyticsBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `insert`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: A unique identifier for the analytics bucket you are creating.
    examples:
      - id: create-analytics-bucket
        name: Create analytics bucket
        isSpotlight: true
        code: |
          ```dart
          final AnalyticsBucket bucket = await supabase
            .storage
            .createAnalyticsBucket('warehouse');
          ```
        response: |
          ```json
          AnalyticsBucket(
            id: 'warehouse',
            name: 'warehouse',
            created_at: '2024-01-01T00:00:00.000Z',
            updated_at: '2024-01-02T00:00:00.000Z'
          )
          ```
  - id: storageanalytics-listbuckets
    description: |
      Retrieves the details of all analytics buckets within an existing project.
    title: 'listAnalyticsBuckets()'
    notes: |
      - Calling `listAnalyticsBuckets()` without any options returns all analytics buckets.
      - Policy permissions required:
        - `buckets` permissions: `select`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: options
        isOptional: true
        type: ListBucketsOptions
        description: Optionally filter, sort and paginate the returned buckets.
        subContent:
          - name: limit
            isOptional: true
            type: int
            description: The maximum number of buckets to return.
          - name: offset
            isOptional: true
            type: int
            description: The number of buckets to skip.
          - name: search
            isOptional: true
            type: String
            description: A search term used to filter buckets by name.
          - name: sortColumn
            isOptional: true
            type: BucketSortColumn
            description: The column to sort the buckets by. One of `BucketSortColumn.id`, `BucketSortColumn.name`, `BucketSortColumn.createdAt` or `BucketSortColumn.updatedAt`.
          - name: sortOrder
            isOptional: true
            type: BucketSortOrder
            description: The direction to sort the buckets in. Either `BucketSortOrder.ascending` or `BucketSortOrder.descending`.
    examples:
      - id: list-analytics-buckets
        name: List analytics buckets
        isSpotlight: true
        code: |
          ```dart
          final List<AnalyticsBucket> buckets = await supabase
            .storage
            .listAnalyticsBuckets();
          ```
        response: |
          ```json
          [
            AnalyticsBucket(
              id: 'warehouse',
              name: 'warehouse',
              created_at: '2024-01-01T00:00:00.000Z',
              updated_at: '2024-01-02T00:00:00.000Z'
            ),
          ]
          ```
      - id: list-analytics-buckets-with-options
        name: With filter, sort and pagination
        code: |
          ```dart
          final List<AnalyticsBucket> buckets = await supabase
            .storage
            .listAnalyticsBuckets(
              const ListBucketsOptions(
                limit: 10,
                offset: 0,
                search: 'ware',
                sortColumn: BucketSortColumn.createdAt,
                sortOrder: BucketSortOrder.descending,
              ),
            );
          ```
  - id: storageanalytics-deletebucket
    description: |
      Deletes an existing analytics bucket. A bucket can't be deleted while it still contains namespaces or tables.
    title: 'deleteAnalyticsBucket()'
    notes: |
      - Policy permissions required:
        - `buckets` permissions: `select` and `delete`
        - `objects` permissions: none
      - Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works
    params:
      - name: id
        isOptional: false
        type: String
        description: The unique identifier of the analytics bucket you would like to delete.
    examples:
      - id: delete-analytics-bucket
        name: Delete analytics bucket
        isSpotlight: true
        code: |
          ```dart
          final String res = await supabase
            .storage
            .deleteAnalyticsBucket('warehouse');
          ```
        response: |
          ```json
          'Successfully deleted'
          ```

  # ---------------------------------------------------------------------------
  # Paginated file listing (list-v2)
  # ---------------------------------------------------------------------------
  - id: vector-buckets
    title: 'Overview'
    category: Storage
    subcategory: Vector Buckets
    notes: |
      This section contains methods for working with Vector Buckets.
  - id: storagevectors-from
    title: 'from()'
    notes: |
      Scopes index operations to a single vector bucket. Returns a `StorageVectorBucketApi`.
    examples:
      - id: vectors-from
        name: Scope operations to a bucket
        isSpotlight: true
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          await bucket.createIndex(
            name: 'documents',
            dimension: 3,
            distanceMetric: DistanceMetric.cosine,
          );
          ```
  - id: storagevectors-create-bucket
    title: 'createBucket()'
    notes: |
      Creates a new vector bucket. Access the vectors client through `supabase.storage.vectors`.
    examples:
      - id: create-vector-bucket
        name: Create a vector bucket
        isSpotlight: true
        code: |
          ```dart
          final vectors = supabase.storage.vectors;

          await vectors.createBucket('embeddings');
          ```
  - id: storagevectors-delete-bucket
    title: 'deleteBucket()'
    notes: |
      Deletes a vector bucket. The bucket must have no indexes before it can be deleted.
    examples:
      - id: delete-vector-bucket
        name: Delete a vector bucket
        isSpotlight: true
        code: |
          ```dart
          final vectors = supabase.storage.vectors;

          await vectors.deleteBucket('embeddings');
          ```
  - id: storagevectors-get-bucket
    title: 'getBucket()'
    notes: |
      Retrieves the metadata of an existing vector bucket.
    examples:
      - id: get-vector-bucket
        name: Get a vector bucket
        isSpotlight: true
        code: |
          ```dart
          final vectors = supabase.storage.vectors;

          final VectorBucket bucket = await vectors.getBucket('embeddings');
          ```
  - id: storagevectors-list-buckets
    title: 'listBuckets()'
    notes: |
      Lists vector buckets. Use `prefix` to filter by name and `maxResults` / `nextToken` to paginate.
    examples:
      - id: list-vector-buckets
        name: List vector buckets
        isSpotlight: true
        code: |
          ```dart
          final vectors = supabase.storage.vectors;

          final VectorBucketList result = await vectors.listBuckets();

          for (final bucket in result.buckets) {
            print(bucket.name);
          }
          ```
      - id: list-vector-buckets-paginated
        name: Paginate and filter buckets
        code: |
          ```dart
          final vectors = supabase.storage.vectors;

          final result = await vectors.listBuckets(
            prefix: 'prod-',
            maxResults: 50,
          );

          final nextToken = result.nextToken;
          ```
  - id: vectorbucket-createindex
    title: 'createIndex()'
    notes: |
      Creates a new vector index in the scoped bucket. `dimension` is the length of the vectors the index will store and `distanceMetric` is the metric used for similarity queries. Keys listed in `nonFilterableMetadataKeys` can be stored on vectors but not used in query filters. `dataType` defaults to `VectorDataType.float32`.
    examples:
      - id: create-index
        name: Create an index
        isSpotlight: true
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          await bucket.createIndex(
            name: 'documents',
            dimension: 3,
            distanceMetric: DistanceMetric.cosine,
          );
          ```
      - id: create-index-non-filterable
        name: Create an index with non-filterable metadata
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          await bucket.createIndex(
            name: 'documents',
            dimension: 3,
            distanceMetric: DistanceMetric.euclidean,
            nonFilterableMetadataKeys: ['rawText'],
          );
          ```
  - id: vectorbucket-deleteindex
    title: 'deleteIndex()'
    notes: |
      Deletes an index and all of its vectors from the scoped bucket.
    examples:
      - id: delete-index
        name: Delete an index
        isSpotlight: true
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          await bucket.deleteIndex('documents');
          ```
  - id: vectorbucket-getindex
    title: 'getIndex()'
    notes: |
      Retrieves the metadata of an index in the scoped bucket.
    examples:
      - id: get-index
        name: Get an index
        isSpotlight: true
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          final VectorIndex index = await bucket.getIndex('documents');

          print(index.dimension);
          print(index.distanceMetric);
          ```
  - id: vectorbucket-listindexes
    title: 'listIndexes()'
    notes: |
      Lists indexes in the scoped bucket. Use `prefix` to filter by name and `maxResults` / `nextToken` to paginate.
    examples:
      - id: list-indexes
        name: List indexes
        isSpotlight: true
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          final VectorIndexList result = await bucket.listIndexes();

          for (final index in result.indexes) {
            print(index.name);
          }
          ```
  - id: vectorbucket-index
    title: 'index()'
    notes: |
      Scopes vector data operations to a single index within a bucket. Returns a `StorageVectorIndexApi`.
    examples:
      - id: bucket-index
        name: Scope operations to an index
        isSpotlight: true
        code: |
          ```dart
          final bucket = supabase.storage.vectors.from('embeddings');

          final index = bucket.index('documents');

          await index.putVectors([
            Vector(key: 'doc-1', data: [0.1, 0.2, 0.3]),
          ]);
          ```
  - id: vectorindex-deletevectors
    title: 'deleteVectors()'
    notes: |
      Deletes vectors by their keys. The batch must contain between 1 and 500 keys.
    examples:
      - id: delete-vectors
        name: Delete vectors
        isSpotlight: true
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          await index.deleteVectors(['doc-1', 'doc-2']);
          ```
  - id: vectorindex-getvectors
    title: 'getVectors()'
    notes: |
      Retrieves vectors by their keys. Set `returnData` and `returnMetadata` to include the embeddings and metadata in the result. Keys that do not exist are omitted from the returned list.
    examples:
      - id: get-vectors
        name: Get vectors by key
        isSpotlight: true
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          final List<VectorMatch> vectors = await index.getVectors(
            keys: ['doc-1', 'doc-2'],
            returnData: true,
            returnMetadata: true,
          );

          for (final vector in vectors) {
            print('${vector.key}: ${vector.metadata}');
          }
          ```
  - id: vectorindex-listvectors
    title: 'listVectors()'
    notes: |
      Lists vectors in the scoped index with pagination. A full-index scan can be distributed across multiple workers by giving each worker a different `segmentIndex` (0 to `segmentCount - 1`) for the same `segmentCount` (1 to 16).
    examples:
      - id: list-vectors
        name: List vectors
        isSpotlight: true
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          final VectorList result = await index.listVectors(
            maxResults: 100,
            returnMetadata: true,
          );

          for (final vector in result.vectors) {
            print(vector.key);
          }
          ```
      - id: list-vectors-parallel-scan
        name: Parallel scan with segments
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          // Worker 2 of a 4-way parallel scan.
          final result = await index.listVectors(
            segmentCount: 4,
            segmentIndex: 2,
          );
          ```
  - id: vectorindex-putvectors
    title: 'putVectors()'
    notes: |
      Inserts or updates a batch of vectors in the scoped index. The batch must contain between 1 and 500 vectors, and each vector's `data` length must match the index dimension.
    examples:
      - id: put-vectors
        name: Put vectors
        isSpotlight: true
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          await index.putVectors([
            Vector(
              key: 'doc-1',
              data: [0.1, 0.2, 0.3],
              metadata: {'title': 'Intro'},
            ),
            Vector(
              key: 'doc-2',
              data: [0.4, 0.5, 0.6],
              metadata: {'title': 'Guide'},
            ),
          ]);
          ```
  - id: vectorindex-queryvectors
    title: 'queryVectors()'
    notes: |
      Searches the scoped index for the vectors most similar to `queryVector`. `topK` limits the number of matches returned. `filter` restricts the search to vectors whose metadata matches the given expression. Set `returnDistance` and `returnMetadata` to include the distance scores and metadata in the result.
    examples:
      - id: query-vectors
        name: Query vectors
        isSpotlight: true
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          final VectorQueryResult result = await index.queryVectors(
            queryVector: [0.1, 0.2, 0.3],
            topK: 5,
            returnDistance: true,
            returnMetadata: true,
          );

          for (final match in result.matches) {
            print('${match.key}: ${match.distance}');
          }
          ```
      - id: query-vectors-filter
        name: Query with a metadata filter
        code: |
          ```dart
          final index = supabase.storage.vectors
              .from('embeddings')
              .index('documents');

          final result = await index.queryVectors(
            queryVector: [0.1, 0.2, 0.3],
            topK: 10,
            filter: {'category': 'docs'},
            returnMetadata: true,
          );
          ```
  - id: using-modifiers
    title: Using Modifiers
    category: Database
    subcategory: Using modifiers
    description: |
      Filters work on the row level. That is, 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: db-modifiers-select
    title: select()
    examples:
      - id: with-upsert
        name: With `upsert()`
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .upsert({ 'id': 1, 'name': 'piano' })
            .select();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'harpsichord');
            ```
        response: |
          ```json
          [
            {
              "id": 1,
              "name": "piano"
            }
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: order
    title: order()
    description: |
      Orders the result with the specified column.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to order by.
      - name: ascending
        isOptional: true
        type: bool
        description: Whether to order in ascending order. Default is `false`.
      - name: nullsFirst
        isOptional: true
        type: bool
        description: Whether to order nulls first. Default is `false`.
      - name: referencedTable
        isOptional: true
        type: String
        description: Specify the referenced table when ordering by a column in an embedded resource.
    examples:
      - id: with-select
        name: With select()
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('id, name')
            .order('id', ascending: false);
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'id': 3,
              'name': 'cello'
            },
            {
              'id': 2,
              'name': 'viola'
            },
            {
              'id': 1,
              'name': 'viola'
            }
          ]
          ```
      - id: on-a-referenced-table
        name: On a referenced table
        code: |
          ```dart
          final data = await supabase
              .from('orchestral_sections')
              .select('''
                name,
                instruments (
                  name
                )
              ''')
              .order('name', referencedTable: 'instruments', ascending: false);
            ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, section_id, name)
            values
              (1, 1, 'harp'),
              (2, 1, 'violin');
            ```
        response: |
          ```json
          [
            {
              'name': 'strings',
              'instruments': [
                {
                  'name': 'violin'
                },
                {
                  'name': 'harp'
                }
              ]
            },
            {
              'name': 'woodwinds',
              'instruments': []
            }
          ]
          ```
      - id: order-parent-table-by-a-referenced-table
        name: Order parent table by a referenced table
        code: |
          ```dart
          final data = await supabase
              .from('instruments')
              .select('''
                name,
                section:orchestral_sections (
                  name
                )
              ''')
              .order('section(name)', ascending: true)
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, section_id, name)
            values
              (1, 1, 'violin'),
              (2, 2, 'flute');
            ```
        response: |
          ```json
          [
            {
              "name": "violin",
              "orchestral_sections": { "name": "strings" }
            },
            {
              "name": "flute",
              "orchestral_sections": { "name": "woodwinds" }
            }
          ]
          ```
  - id: limit
    title: limit()
    description: |
      Limits the result with the specified count.
    params:
      - name: count
        isOptional: false
        type: int
        description: The maximum number of rows to return.
      - name: referencedTable
        isOptional: true
        type: int
        description: Set this to limit rows of referenced tables instead of the parent table.
    examples:
      - id: with-select
        name: With select()
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('name')
            .limit(1);
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'name': 'violin'
            }
          ]
          ```
      - id: on-a-referenced-table
        name: On a referenced table
        code: |
          ```dart
          final data = await supabase
            .from('orchestral_sections')
            .select('''
              name,
              instruments (
                name
              )
            ''')
            .limit(1, referencedTable: 'instruments');
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings');
            insert into
              instruments (id, section_id, name)
            values
              (1, 1, 'violin'),
              (2, 1, 'viola');
            ```
        response: |
          ```json
          [
            {
              'name': 'strings',
              'instruments': [
                {
                  'name': 'violin'
                }
              ]
            }
          ]
          ```
  - id: range
    title: range()
    description: |
      Limits the result to rows within the specified range, inclusive.
    params:
      - name: from
        isOptional: false
        type: int
        description: The starting index from which to limit the result.
      - name: to
        isOptional: false
        type: int
        description: The last index to which to limit the result.
      - name: referencedTable
        isOptional: true
        type: String
        description: Set this to limit rows of referenced tables instead of the parent table.
    examples:
      - id: with-select
        name: With select()
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('name')
            .range(0, 1);
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'name': 'violin'
            },
            {
              'name': 'viola'
            }
          ]
          ```
  - id: max-affected
    title: maxAffected()
    description: |
      Sets the maximum number of rows that can be affected by the query. Only effective with PATCH and DELETE operations. Requires PostgREST v13 or higher.

      When the limit is exceeded, the query will fail with an error. This provides a safety mechanism to prevent accidentally affecting more rows than intended.
    notes: |
      - This method is only effective with UPDATE and DELETE operations.
      - Requires PostgREST v13 or higher on your Supabase instance.
      - If the number of affected rows exceeds the limit, the query will fail and no rows will be modified.
    params:
      - name: count
        isOptional: false
        type: int
        description: The maximum number of rows that can be affected by the query.
    examples:
      - id: with-update
        name: With update()
        isSpotlight: true
        code: |
          ```dart
          await supabase
            .from('users')
            .update({'active': false})
            .eq('status', 'inactive')
            .maxAffected(5);
          ```
        description: |
          Limit the number of rows that can be updated. If more than 5 rows match the filter, the operation will fail.
      - id: with-delete
        name: With delete()
        code: |
          ```dart
          await supabase
            .from('users')
            .delete()
            .eq('active', false)
            .maxAffected(10);
          ```
        description: |
          Limit the number of rows that can be deleted. If more than 10 rows match the filter, the operation will fail.
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('users')
            .update({'status': 'INACTIVE'})
            .eq('id', 1)
            .maxAffected(1)
            .select();
          ```
        description: |
          Combine maxAffected with select() to limit affected rows and return the updated data.
  - id: single
    title: single()
    description: |
      Retrieves only one row from the result. Result must be one row (e.g. using limit), otherwise this will result in an error.
    examples:
      - id: with-select
        name: With select()
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('name')
            .limit(1)
            .single();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          {
            'name': 'violin'
          }
          ```
  - id: maybe-single
    title: maybeSingle()
    examples:
      - id: with-select
        name: With `select()`
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select()
            .eq('name', 'guzheng')
            .maybeSingle();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          null
          ```
        hideCodeBlock: true
        isSpotlight: true
  - id: csv
    title: csv()
    examples:
      - id: return-data-as-csv
        name: Return data as CSV
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select()
            .csv();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          'id,name\n1,violin\n2,viola\n3,cello'
          ```
        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
    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.
    params:
      - name: analyze
        isOptional: true
        type: bool
        description: If `true`, the query will be executed and the actual run time will be returned.
      - name: verbose
        isOptional: true
        type: bool
        description: If `true`, the query identifier will be returned and `data` will include the output columns of the query.
      - name: settings
        isOptional: true
        type: bool
        description: If `true`, include information on configuration parameters that affect query planning.
      - name: buffers
        isOptional: true
        type: bool
        description: If `true`, include information on buffer usage.
      - name: wal
        isOptional: true
        type: bool
        description: If `true`, include information on WAL record generation.
      - name: format
        isOptional: true
        type: ExplainFormat
        description: The output format of the execution plan. Either `ExplainFormat.text` (default) or `ExplainFormat.json`, in which case the plan is returned as a JSON string.
    examples:
      - id: get-execution-plan
        name: Get the execution plan
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select()
            .explain();
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```
          Aggregate  (cost=33.34..33.36 rows=1 width=112)
            ->  Limit  (cost=0.00..18.33 rows=1000 width=40)
                  ->  Seq Scan on instruments  (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: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select()
            .explain(analyze:true, verbose:true);
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        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(instruments.id, instruments.name)), COALESCE(json_agg(ROW(instruments.id, instruments.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: instruments.id, instruments.name
                  ->  Seq Scan on public.instruments  (cost=0.00..22.00 rows=1200 width=40) (actual time=0.004..0.005 rows=3 loops=1)
                        Output: instruments.id, instruments.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: strip-nulls
    title: 'stripNulls()'
    description: |
      Omits `null`-valued properties from the response objects.
    notes: |
      - This uses the `nulls=stripped` variant of the `Accept` header and requires PostgREST 11.2 or higher.
    examples:
      - id: strip-null-values-from-the-response
        name: Strip null values from the response
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('users')
            .select()
            .stripNulls();
          ```
  - id: using-filters
    title: Using Filters
    category: Database
    subcategory: 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 Database 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/dart/using-modifiers).
        code: |
          ```dart
          final data = await supabase
            .from('cities')
            .select('name, country_id')
            .eq('name', 'The Shire');  // Correct

          final data = await supabase
            .from('cities')
            .eq('name', 'The Shire')  // Incorrect
            .select('name, country_id');
          ```
      - id: chaining-filters
        name: Chaining Filters
        description: |
          Filters can be chained together to produce advanced queries as shown in the example code.
        code: |
          ```dart
          final data = await supabase
            .from('cities')
            .select('name, country_id')
            .gte('population', 1000)
            .lt('population', 10000)
          ```
      - id: conditional-chaining
        name: Conditional Chaining
        description: |
          Filters can be built up one step at a time and then executed as shown in the example code.
        code: |
          ```dart
          final filterByName = null;
          final filterPopLow = 1000;
          final filterPopHigh = 10000;

          var query = supabase
            .from('cities')
            .select('name, country_id');

          if (filterByName != null) query = query.eq('name', filterByName);
          if (filterPopLow != null) query = query.gte('population', filterPopLow);
          if (filterPopHigh != null) query = query.lt('population', filterPopHigh);

          final data = await query;
          ```
      - id: filter-by-value-within-json-column
        name: Filter by values within a JSON column
        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
          [
            {
              'id': 1,
              'name': 'Michael',
              'address': {
                'postcode': 90210
              }
            },
          ]
          ```
        code: |
          ```dart
          final data = await supabase
            .from('users')
            .select()
            .eq('address->postcode', 90210);
          ```
      - id: filter-referenced-tables
        name: Filter Referenced Tables
        code: |
          ```dart
          final data = await supabase
            .from('orchestral_sections')
            .select('''
              name,
              instruments!inner (
                name
              )
            ''')
            .eq('instruments.name', 'flute');
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, section_id, name)
            values
              (1, 2, 'flute'),
              (2, 1, 'violin');
            ```
        response: |
          ```json
          [
            {
              'name': 'strings',
              'instruments': [
                {
                  'name': 'flute'
                }
              ]
            },
          ]
          ```
        description: |
          You can filter on referenced tables in your `select()` query using dot
          notation.
  - id: or
    title: or()
    description: |
      Finds all rows satisfying at least one of the filters.
    params:
      - name: filters
        isOptional: false
        type: String
        description: The filters to use, following PostgREST syntax
      - name: referencedTable
        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](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values.

        ```dart
        .or('id.in.(6,7),arraycol.cs.{"a","b"}')  // Use Postgres list () and 'in' instead of `inFilter`. Array {} and 'cs' for contains.
        .or('id.in.(${mylist.join(',')}),arraycol.cs.{${mylistArray.join(',')}}')	// You can insert a Dart list for list or array column.
        .or('id.in.(${mylist.join(',')}),rangecol.cs.(${mylistRange.join(',')}]')	// You can insert a Dart list for list or range column.
        ```
    examples:
      - id: with-select
        name: With select()
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('name')
            .or('id.eq.2,name.eq.cello');
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'name': 'viola'
            },
            {
              'name': 'cello'
            }
          ]
          ```
      - id: use-or-with-and
        name: Use `or` with `and`
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('name')
            .or('id.gt.3,and(id.eq.1,name.eq.violin)');
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'name': 'violin'
            }
          ]
          ```
      - id: use-or-on-referenced-tables
        name: Use `or` on referenced tables
        code: |
          ```dart
          final data = await supabase
            .from('orchestral_sections')
            .select('''
              name,
              instruments!inner (
                name
              )
            ''')
            .or('section_id.eq.1,name.eq.guzheng', referencedTable: 'instruments' );
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, book_id, name)
            values
              (1, 2, 'flute'),
              (2, 1, 'violin');
            ```
        response: |
          ```json
          [
            {
              'name': 'strings',
              'instruments': [
                {
                  'name': 'violin'
                }
              ]
            }
          ]
          ```
        hideCodeBlock: true

  - id: not
    title: not()
    description: |
      Finds all rows which doesn't satisfy the filter.
    notes: |
      - `.not()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values.

        ```dart
        .not('name','eq','violin')
        .not('arraycol','cs','{"a","b"}') // Use Postgres array {} for array column and 'cs' for contains.
        .not('rangecol','cs','(1,2]') // Use Postgres range syntax for range column.
        .not('id','in','(6,7)')  // Use Postgres list () and 'in' instead of `inFilter`.
        .not('id','in','(${mylist.join(',')})')  // You can insert a Dart list array.
        ```
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: operator
        isOptional: false
        type: String
        description: The operator to be negated to filter with, following PostgREST syntax.
      - name: value
        isOptional: true
        type: Object
        description: The value to filter with, following PostgREST syntax.
    examples:
      - id: with-select
        name: With select()
        isSpotlight: false
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .select()
            .not('name', 'is', null)
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'null'),
              (2, null);
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'null'
            }
          ]
          ```
      - id: with-update
        name: With update()
        code: |
          ```dart
          final data = await supabase
            .from('cities')
            .update({ 'name': 'Mordor' })
            .not('name', 'eq', 'Rohan');
          ```
      - id: with-delete
        name: With delete()
        code: |
          ```dart
          final data = await supabase
            .from('cities')
            .delete()
            .not('name', 'eq', 'Mordor');
          ```
      - id: with-rpc
        name: With rpc()
        code: |
          ```dart
          // Only valid if the database function returns a table type.
          final data = await supabase
            .rpc('echo_all_cities')
            .not('name', 'eq', 'Mordor');
          ```

  - id: match
    title: match()
    description: |
      Finds all rows whose columns match the specified `query` object.
    params:
      - name: query
        isOptional: false
        type: Map<String, dynamic>
        description: The object to filter with, with column names as keys mapped to their filter values
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select()
            .match({ 'id': 2, 'name': 'viola' });
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'name': 'viola'
            }
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - 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: Object
        description: The value to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select()
            .eq('name', 'viola');
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'id': 2,
              'name': 'viola'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: neq
    title: neq()
    description: |
      Finds all rows whose value on the stated `column` doesn't match the specified `value`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: value
        isOptional: false
        type: Object
        description: The value to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .select('id, name')
            .neq('name', 'viola');
          ```
        data:
          sql: |
            ```sql
            create table
              instruments (id int8 primary key, name text);

            insert into
              instruments (id, name)
            values
              (1, 'violin'),
              (2, 'viola'),
              (3, 'cello');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'violin'
            },
            {
              'id': 3,
              'name': 'cello'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: gt
    title: gt()
    description: |
      Finds all rows whose value on the stated `column` is greater than the specified `value`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: value
        isOptional: false
        type: Object
        description: The value to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .select()
            .gt('id', 2);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Rohan'),
              (2, 'The Shire'),
              (3, 'Mordor');
            ```
        response: |
          ```json
          [
            {
              'id': 3,
              'name': 'Mordor'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: gte
    title: gte()
    description: |
      Finds all rows whose value on the stated `column` is greater than or equal to the specified `value`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: value
        isOptional: false
        type: Object
        description: The value to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .select()
            .gte('id', 2);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Rohan'),
              (2, 'The Shire'),
              (3, 'Mordor');
            ```
        response: |
          ```json
          [
            {
              'id': 2,
              'name': 'The Shire'
            },
            {
              'id': 3,
              'name': 'Mordor'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: lt
    title: lt()
    description: |
      Finds all rows whose value on the stated `column` is less than the specified `value`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: value
        isOptional: false
        type: Object
        description: The value to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .select()
            .lt('id', 2);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Rohan'),
              (2, 'The Shire'),
              (3, 'Mordor');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'Rohan'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: lte
    title: lte()
    description: |
      Finds all rows whose value on the stated `column` is less than or equal to the specified `value`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: value
        isOptional: false
        type: Object
        description: The value to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .select()
            .lte('id', 2);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'Rohan'),
              (2, 'The Shire'),
              (3, 'Mordor');
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'Rohan'
            },
            {
              'id': 2,
              'name': 'The Shire'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: like
    title: like()
    description: |
      Finds all rows whose value in the stated `column` matches the supplied `pattern` (case sensitive).
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: pattern
        isOptional: false
        type: String
        description: The pattern to match with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('planets')
            .select()
            .like('name', '%Ea%');
          ```
        data:
          sql: |
            ```sql
            create table
              planets (id int8 primary key, name text);

            insert into
              planets (id, name)
            values
              (1, 'Mercury'),
              (2, 'Earth'),
              (3, 'Mars');
            ```
        response: |
          ```json
          [
            {
              'id': 2,
              'name': 'Earth'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: ilike
    title: ilike()
    description: |
      Finds all rows whose value in the stated `column` matches the supplied `pattern` (case insensitive).
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: pattern
        isOptional: false
        type: String
        description: The pattern to match with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('planets')
            .select()
            .ilike('name', '%ea%');
          ```
        data:
          sql: |
            ```sql
            create table
              planets (id int8 primary key, name text);

            insert into
              planets (id, name)
            values
              (1, 'Mercury'),
              (2, 'Earth'),
              (3, 'Mars');
            ```
        response: |
          ```json
          [
            {
              'id': 2,
              'name': 'Earth'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true

  - id: is
    title: isFilter()
    description: |
      A check for exact equality (null, true, false), finds all rows whose value on the stated `column` exactly match the specified `value`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: value
        isOptional: false
        type: Object?
        description: The value to filter with.
    examples:
      - id: checking-nullness
        name: Checking for nullness, true or false
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .select()
            .isFilter('name', null);
          ```
        data:
          sql: |
            ```sql
            create table
              countries (id int8 primary key, name text);

            insert into
              countries (id, name)
            values
              (1, 'null'),
              (2, null);
            ```
        response: |
          ```json
          [
            {
              'id': 1,
              'name': 'null'
            },
          ]
          ```
        description: |
          Using the `eq()` filter doesn't work when filtering for `null`.

          Instead, you need to use `isFilter()`.

          `isFilter()` is equivalent to `is()` in SDKs for other languages. It's named `isFilter()` in Dart to avoid a conflict with the `is` keyword in Dart.
        hideCodeBlock: true
        isSpotlight: true

  - id: in
    title: inFilter()
    description: |
      Finds all rows whose value on the stated `column` is found on the specified `values`.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: values
        isOptional: false
        type: List
        description: The List to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('characters')
            .select()
            .inFilter('name', ['Luke', 'Leia']);
          ```
        data:
          sql: |
            ```sql
            create table
              characters (id int8 primary key, name text);

            insert into
              characters (id, name)
            values
              (1, 'Han'),
              (2, 'Luke'),
              (3, 'Leia');
            ```
        response: |
          ```json
          [
            {
              'id': 2,
              'name': 'Luke'
            },
            {
              'id': 3,
              'name': 'Leia'
            },
          ]
          ```
        description: |
          `inFilter()` is equivalent to `in()` in SDKs for other languages. It's named `inFilter()` in Dart to avoid a conflict with the `in` keyword in Dart.
        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 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
        description: |
          Only relevant for jsonb, array, and range columns. Match only rows where `column` contains every element appearing in `value`.
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('issues')
            .select()
            .contains('tags', ['is:open', 'priority:low']);
          ```
        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
          [
            {
              'id': 1,
              'title': 'Cache invalidation is not working',
              'tags': ['is:open', 'severity:high', 'priority:low']
            },
          ]
          ```
        hideCodeBlock: true
      - id: on-range-columns
        name: On range columns
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .contains('during', '[2000-01-01 13:00, 2000-01-01 13:30)');
          ```
        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
          [
            {
              'id': 1,
              'room_name': 'Emerald',
              'during': '["2000-01-01 13:00:00","2000-01-01 15:00:00")'
            },
          ]
          ```
        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: |
          ```dart
          final data = await supabase
            .from('users')
            .select('name')
            .contains('address', { 'street': 'Melrose Place' });
          ```
        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', '{"postcode": 90210}');
            ```
        response: |
          ```json
          [
            {
              'name': 'Michael'
            },
          ]
          ```
        hideCodeBlock: true

  - id: contained-by
    title: containedBy()
    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
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('classes')
            .select('name')
            .containedBy('days', ['monday', 'tuesday', 'wednesday', 'friday']);
          ```
        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
          [
            {
              'name': 'Chemistry'
            },
          ]
          ```
        hideCodeBlock: true
      - id: on-range-columns
        name: On range columns
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .containedBy('during', '[2000-01-01 00:00, 2000-01-01 23:59)');
          ```
        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
          [
            {
              'id': 1,
              'room_name': 'Emerald',
              'during': '["2000-01-01 13:00:00","2000-01-01 15:00:00")'
            },
          ]
          ```
        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: |
          ```dart
          final data = await supabase
            .from('users')
            .select('name')
            .containedBy('address', {'postcode': 90210});
          ```
        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', '{"postcode": 90210}');
            ```
        response: |
          ```json
            [
              {
                'name': 'Jane'
              },
            ]
            ```
        hideCodeBlock: true

  - id: range-lt
    title: rangeLt()
    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: String
        description: The range to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .rangeLt('during', '[2000-01-01 15:00, 2000-01-01 16:00)');
          ```
        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
          [
            {
              'id': 1,
              'room_name': 'Emerald',
              'during': '["2000-01-01 13:00:00","2000-01-01 15:00:00")'
            },
          ]
          ```
        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-gt
    title: rangeGt()
    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: String
        description: The range to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .rangeGt('during', '[2000-01-02 08:00, 2000-01-02 09:00)');
          ```
        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
          [
            {
              'id': 2,
              'room_name': 'Topaz',
              'during': '["2000-01-02 09:00:00","2000-01-02 10:00:00")'
            }
          ]
          ```
        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: rangeGte()
    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: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .rangeGte('during', '[2000-01-02 08:30, 2000-01-02 09:30)');
          ```
        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
          [
            {
              'id': 2,
              'room_name': 'Topaz',
              'during': '["2000-01-02 09:00:00","2000-01-02 10:00:00")''
            },
          ]
          ```
        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: rangeLte()
    description: |
      Only relevant for range columns. Match only rows where every element in `column` is either contained in `range` or 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: String
        description: The range to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .rangeLte('during', '[2000-01-01 15:00, 2000-01-01 16:00)');
          ```
        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
          [
            {
              'id': 1,
              'room_name': 'Emerald',
              'during': '["2000-01-01 13:00:00","2000-01-01 15:00:00")'
            },
          ]
          ```
        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: rangeAdjacent()
    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: String
        description: The range to filter with.
    examples:
      - id: with-select
        name: With select()
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .rangeAdjacent('during', '[2000-01-01 12:00, 2000-01-01 13:00)');
          ```
        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
          [
            {
              'id': 1,
              'room_name': 'Emerald',
              'during': '["2000-01-01 13:00:00","2000-01-01 15:00:00")'
            },
          ]
          ```
        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: Object
        description: The array or range value to filter with.
    examples:
      - id: on-array-columns
        name: On array columns
        code: |
          ```dart
          final data = await supabase
            .from('issues')
            .select('title')
            .overlaps('tags', ['is:closed', 'severity:high']);
          ```
        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
          [
            {
              'title': 'Cache invalidation is not working'
            },
          ]
          ```
        hideCodeBlock: true
        isSpotlight: true
      - id: on-range-columns
        name: On range columns
        code: |
          ```dart
          final data = await supabase
            .from('reservations')
            .select()
            .overlaps('during', '[2000-01-01 12:45, 2000-01-01 13:15)');
          ```
        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
          [
            {
              'id': 1,
              'room_name': 'Emerald',
              'during': '["2000-01-01 13:00:00","2000-01-01 15:00:00")'
            },
          ]
          ```
        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: textSearch()
    description: |
      Finds all rows whose tsvector value on the stated `column` matches to_tsquery(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: config
        isOptional: true
        type: String
        description: The text search configuration to use.
      - name: type
        isOptional: true
        type: TextSearchType
        description: Change how the `query` text is interpreted.
    examples:
      - id: text-search
        name: Text search
        code: |
          ```dart
          final data = await supabase
            .from('quotes')
            .select('catchphrase')
            .textSearch('content', "'eggs' & 'ham'",
              config: 'english'
            );
          ```
        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
          [
            {
              'content': 'Green eggs and ham'
            }
          ]
          ```
      - id: basic-normalization
        name: Basic normalization
        description: Uses PostgreSQL's `plainto_tsquery` function.
        code: |
          ```dart
          final data = await supabase
            .from('quotes')
            .select('catchphrase')
            .textSearch('catchphrase', "'fat' & 'cat'",
              type: TextSearchType.plain,
              config: 'english'
            );
          ```
      - id: full-normalization
        name: Full normalization
        description: Uses PostgreSQL's `phraseto_tsquery` function.
        code: |
          ```dart
          final data = await supabase
            .from('quotes')
            .select('catchphrase')
            .textSearch('catchphrase', "'fat' & 'cat'",
              type: TextSearchType.phrase,
              config: 'english'
            );
          ```
      - 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: |
          ```dart
          final data = await supabase
            .from('quotes')
            .select('catchphrase')
            .textSearch('catchphrase', "'fat or cat'",
              type: TextSearchType.websearch,
              config: 'english'
            );
          ```

  - id: filter
    title: filter()
    description: |
      Match only rows which satisfy the filter. This is an escape hatch - you should use the specific filter methods wherever possible.
    params:
      - name: column
        isOptional: false
        type: String
        description: The column to filter on.
      - name: operator
        isOptional: false
        type: String
        description: The operator to filter with, following PostgREST syntax.
      - name: value
        isOptional: false
        type: Object
        description: The value to filter with, following PostgREST syntax.
    notes: |
      `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work.
      ```dart
      .filter('arraycol','cs','{"a","b"}') // Use Postgres array {} and 'cs' for contains.
      .filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column.
      .filter('id','in','(6,7)')  // Use Postgres list () and 'in' for in_ filter.
      .filter('id','cs','{${mylist.join(',')}}')  // You can insert a Dart array list.
      ```
    examples:
      - id: with-select
        name: With select()
        isSpotlight: true
        code: |
          ```dart
          final data = await supabase
            .from('characters')
            .select()
            .filter('name', 'in', '("Ron","Dumbledore")')
          ```
        data:
          sql: |
            ```sql
            create table
              characters (id int8 primary key, name text);

            insert into
              characters (id, name)
            values
              (1, 'Harry'),
              (2, 'Hermione'),
              (3, 'Ron');
            ```
        response: |
          ```json
          [
            {
              'id': 3,
              'name': 'Ron'
            }
          ]
          ```
      - id: with-update
        name: With update()
        code: |
          ```dart
          final data = await supabase
            .from('instruments')
            .update({ 'name': 'piano' })
            .filter('name', 'in', '("harpsichord","clavichord")');
          ```
      - id: with-delete
        name: With delete()
        code: |
          ```dart
          final data = await supabase
            .from('countries')
            .delete()
            .filter('name', 'in', '("Rohan","Mordor")');
          ```
      - id: with-rpc
        name: With rpc()
        code: |
          ```dart
          // Only valid if the database function returns a table type.
          final data = await supabase
            .rpc('echo_all_countries')
            .filter('name', 'in', '("Rohan","Mordor")');
          ```
      - id: on-a-referenced-table
        name: On a referenced table
        code: |
          ```dart
          final data = await supabase
            .from('orchestral_sections')
            .select('''
              name,
              instruments!inner (
                name
              )
            ''')
            .filter('characters.name', 'eq', 'flute')
          ```
        data:
          sql: |
            ```sql
            create table
              orchestral_sections (id int8 primary key, name text);
            create table
              instruments (
                id int8 primary key,
                section_id int8 not null references orchestral_sections,
                name text
              );

            insert into
              orchestral_sections (id, name)
            values
              (1, 'strings'),
              (2, 'woodwinds');
            insert into
              instruments (id, section_id, name)
            values
              (1, 2, 'flute'),
              (2, 1, 'violin');
            ```
        response: |
          ```json
          [
            {
              'name': 'woodwinds',
              'instruments': [
                {
                  'name': 'flute'
                }
              ]
            }
          ]
          ```
        hideCodeBlock: true