Initialize the CocoIndex Library

Before everything starts, the CocoIndex library needs to be initialized with settings. We'll talk about the code skeleton to initialize the library in your code, and the way to provide settings for CocoIndex.

Initialize the library

There're two options to initialize in your code:

• Use packaged main function. It's easier to start with.
• Explicit initialization. It's more flexible.

Packaged Main

The easiest way is to use a packaged main function:

Python

The @cocoindex.main_fn decorator wraps your main function for CocoIndex:

import cocoindex

@cocoindex.main_fn()
def main():
  ...

if __name__ == "__main__":
  main()

This takes care of the following effects:

1. Initialize the library with settings loaded from environment variables, if not explicitly provided.
2. If the program is executed with the cocoindex command, CocoIndex CLI will take over the control. It provides a bunch of commands for easily managing and inspecting indexes. See CocoIndex CLI for more details.
3. Otherwise, it will run the main function.

See Environment Variables for supported environment variables.

Explicit Initialization

Alternatively, for flexibility, you can also explicitly initialize the library by the init() function:

Python

import cocoindex

def main():
  ...
  cocoindex.init(
      cocoindex.Settings(
          database=cocoindex.DatabaseConnectionSpec(
              url="postgres://cocoindex:cocoindex@localhost/cocoindex"
  )))
  ...

...
if __name__ == "__main__":
  main()

Settings

cocoindex.Settings is used to configure the CocoIndex library. It's a dataclass that contains the following fields:

• database (type: DatabaseConnectionSpec, required): The connection to the Postgres database.

DatabaseConnectionSpec

DatabaseConnectionSpec configures the connection to a database. Only Postgres is supported for now. It has the following fields:

• url (type: str, required): The URL of the Postgres database to use as the internal storage, e.g. postgres://cocoindex:cocoindex@localhost/cocoindex.
• user (type: str, optional): The username for the Postgres database. If not provided, username will come from url.
• password (type: str, optional): The password for the Postgres database. If not provided, password will come from url.

tip

Please be careful that all values in url needs to be url-encoded if they contain special characters. For this reason, prefer to use the separated user and password fields for username and password.

info

If you use the Postgres database hosted by Supabase, please click Connect on your project dashboard and find the following URL:

• If you're on a IPv6 network, use the URL under Direct connection. You can visit IPv6 test to see if you have IPv6 Internet connection.
• Otherwise, use the URL under Session pooler.

Environment Variables

When you use the packaged main function, settings will be loaded from environment variables. Each setting field has a corresponding environment variable:

environment variable	corresponding field in Settings	required?
COCOINDEX_DATABASE_URL	database.url	Yes
COCOINDEX_DATABASE_USER	database.user	No
COCOINDEX_DATABASE_PASSWORD	database.password	No