|
| 1 | +--- |
| 2 | +title: CocoIndex Settings |
| 3 | +description: Provide settings for CocoIndex, e.g. database connection, app namespace, etc. |
| 4 | +--- |
| 5 | + |
| 6 | +import Tabs from '@theme/Tabs'; |
| 7 | +import TabItem from '@theme/TabItem'; |
| 8 | + |
| 9 | +# CocoIndex Settings |
| 10 | + |
| 11 | +Certain settings need to be provided for CocoIndex to work, e.g. database connections, app namespace, etc. |
| 12 | + |
| 13 | +## Launch CocoIndex |
| 14 | + |
| 15 | +You have two ways to launch CocoIndex: |
| 16 | + |
| 17 | +* Use [Cocoindex CLI](cli). It's handy for most routine indexing building and management tasks. |
| 18 | + It will load settings from environment variables, either already set in your environment, or specified in `.env` file. |
| 19 | + See [CLI](cli#environment-variables) for more details. |
| 20 | + |
| 21 | +* Call CocoIndex functionality from your own Python application or library. |
| 22 | + It's needed when you want to leverage CocoIndex support for query, or have your custom logic to trigger indexing, etc. |
| 23 | + |
| 24 | + <Tabs> |
| 25 | + <TabItem value="python" label="Python" default> |
| 26 | + |
| 27 | + You need to explicitly call `cocoindex.init()` before doing anything with CocoIndex, and settings will be loaded during the call. |
| 28 | + |
| 29 | + * If it's called without any argument, it will load settings from environment variables. |
| 30 | + Only existing environment variables already set in your environment will be used. |
| 31 | + If you want to load environment variables from a specific `.env` file, consider call `load_dotenv()` provided by the [`python-dotenv`](https://github.com/theskumar/python-dotenv) package. |
| 32 | + |
| 33 | + ```py |
| 34 | + from dotenv import load_dotenv |
| 35 | + import cocoindex |
| 36 | + |
| 37 | + load_dotenv() |
| 38 | + cocoindex.init() |
| 39 | + ``` |
| 40 | + |
| 41 | + * It takes an optional `cocoindex.Settings` dataclass object as argument, so you can also construct settings explicitly and pass to it: |
| 42 | + |
| 43 | + ```py |
| 44 | + import cocoindex |
| 45 | + |
| 46 | + cocoindex.init( |
| 47 | + cocoindex.Settings( |
| 48 | + database=cocoindex.DatabaseConnectionSpec( |
| 49 | + url="postgres://cocoindex:cocoindex@localhost/cocoindex" |
| 50 | + ) |
| 51 | + ) |
| 52 | + ) |
| 53 | + ``` |
| 54 | + </TabItem> |
| 55 | + </Tabs> |
| 56 | + |
| 57 | +## List of Settings |
| 58 | + |
| 59 | +`cocoindex.Settings` is a dataclass that contains the following fields: |
| 60 | + |
| 61 | +* `app_namespace` (type: `str`, required): The namespace of the application. |
| 62 | +* `database` (type: `DatabaseConnectionSpec`, required): The connection to the Postgres database. |
| 63 | + |
| 64 | +### App Namespace |
| 65 | + |
| 66 | +The `app_namespace` field helps organize flows across different environments (e.g., dev, staging, production), team members, etc. When set, it prefixes flow names with the namespace. |
| 67 | + |
| 68 | +For example, if the namespace is `Staging`, for a flow with name specified as `Flow1` in code, the full name of the flow will be `Staging.Flow1`. |
| 69 | +You can also get the current app namespace by calling `cocoindex.get_app_namespace()` (see [Getting App Namespace](flow_def#getting-app-namespace) for more details). |
| 70 | + |
| 71 | +If not set, all flows are in a default unnamed namespace. |
| 72 | + |
| 73 | +*Environment variable*: `COCOINDEX_APP_NAMESPACE` |
| 74 | + |
| 75 | +### DatabaseConnectionSpec |
| 76 | + |
| 77 | +`DatabaseConnectionSpec` configures the connection to a database. Only Postgres is supported for now. It has the following fields: |
| 78 | + |
| 79 | +* `url` (type: `str`, required): The URL of the Postgres database to use as the internal storage, e.g. `postgres://cocoindex:cocoindex@localhost/cocoindex`. |
| 80 | + |
| 81 | + *Environment variable* for `Settings.database.url`: `COCOINDEX_DATABASE_URL` |
| 82 | + |
| 83 | +* `user` (type: `str`, optional): The username for the Postgres database. If not provided, username will come from `url`. |
| 84 | + |
| 85 | + *Environment variable* for `Settings.database.user`: `COCOINDEX_DATABASE_USER` |
| 86 | + |
| 87 | +* `password` (type: `str`, optional): The password for the Postgres database. If not provided, password will come from `url`. |
| 88 | + |
| 89 | + *Environment variable* for `Settings.database.password`: `COCOINDEX_DATABASE_PASSWORD` |
| 90 | + |
| 91 | +:::tip |
| 92 | + |
| 93 | +Please be careful that all values in `url` needs to be url-encoded if they contain special characters. |
| 94 | +For this reason, prefer to use the separated `user` and `password` fields for username and password. |
| 95 | + |
| 96 | +::: |
| 97 | + |
| 98 | +:::info |
| 99 | + |
| 100 | +If you use the Postgres database hosted by [Supabase](https://supabase.com/), please click **Connect** on your project dashboard and find the following URL: |
| 101 | + |
| 102 | +* If you're on a IPv6 network, use the URL under **Direct connection**. You can visit [IPv6 test](https://test-ipv6.com/) to see if you have IPv6 Internet connection. |
| 103 | +* Otherwise, use the URL under **Session pooler**. |
| 104 | + |
| 105 | +::: |
| 106 | + |
| 107 | +## List of Environment Variables |
| 108 | + |
| 109 | +This is the list of environment variables, each of which has a corresponding field in `Settings`: |
| 110 | + |
| 111 | +| environment variable | corresponding field in `Settings` | required? | |
| 112 | +|---------------------|-------------------|----------| |
| 113 | +| `COCOINDEX_DATABASE_URL` | `database.url` | Yes | |
| 114 | +| `COCOINDEX_DATABASE_USER` | `database.user` | No | |
| 115 | +| `COCOINDEX_DATABASE_PASSWORD` | `database.password` | No | |
| 116 | +| `COCOINDEX_APP_NAMESPACE` | `app_namespace` | No | |
0 commit comments