> For the complete documentation index, see [llms.txt](https://docs.sdv.dev/sdv/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sdv.dev/sdv/integration/db/api.md).
# ❖ Usage API
{% hint style="info" %}
❖ **SDV Enterprise Bundle**. This feature is available as part of the **AI Connectors Bundle**, an optional add-on to SDV Enterprise. For more information, please visit the [AI Connectors Bundle](/sdv/explore/sdv-bundles/ai-connectors.md) page.
{% endhint %}
Once you completed [integration](/sdv/integration/db/integration.md), you should have a database connector object that is ready to use. Use the API endpoints below to create metadata and import training data to use with SDV.
## Importing Data
Import data from your database to use with SDV.
### ❖ set\_import\_config
Use this function to authenticate into the project and database you'd like to import from.
```python
connector.set_import_config(filepath='source_db_config.yaml')
```
**Parameters**
* (required) `filepath`: A string with the filepath that contains your configuration options. This should be a YAML file that ends in `.yaml`. For more information see section for [Configuration](/sdv/integration/db/integration.md).
**Output** (None)
### ❖ create\_metadata
Use this function to create metadata based on the connection to your database.
```python
metadata = connector.create_metadata(
table_names=['users', 'transactions', 'sessions'])
```
**Parameters**
* `table_names`: A list of strings representing the table names that you want to create metadata for
* (default) `None`: Create metadata for all the tables in the database
* `infer_sdtypes`: A boolean describing whether to infer the sdtypes of each column
* (default) `True`: Infer the sdtypes based on the data
* `False`: Do not infer the sdtypes. All columns will be marked as `unknown`, ready for you to manually update
* `infer_keys`: A string describing whether to infer the primary and/or foreign keys. Options are:
* (default) `'primary_and_foreign'`: Infer the primary keys in each table, and the foreign keys in other tables that refer to them
* `'primary_only'`: Infer only the primary keys of each table
* `None`: Do not infer any keys
**Output** A [Metadata](/sdv/integration/metadata.md) object
{% hint style="warning" %}
**The detected metadata is not guaranteed to be accurate or complete.** Be sure to carefully inspect the metadata and update information. For more information, see the [Metadata API](/sdv/integration/metadata/metadata-api.md).
{% endhint %}
### ❖ import\_random\_subset
Use this function to import a random subset of your data from the database and inferred metadata. The size of the subset is automatically determined.
```python
data = connector.import_random_subset(
metadata=metadata,
verbose=True
)
```
**Parameters**
* (required) `metadata`: A [Metadata](/sdv/integration/metadata.md) object that describes the data you want to import
* `fixed_seed`: A boolean that controls the determinism of the random subset
* (default) `False`: Different random data will be imported every time you call the function
* `True`: The same data will be imported every time you import
* `verbose`: A boolean describing whether to print out details about the progress of the import
* (default) `True`: Print out the table names and number of rows being imported
* `False`: Do not print any details
**Output** A dictionary that maps each table name of your database (string) to the data, represented as a pandas DataFrame.
### ❖ import\_optimized\_subset
Use this function to import a subset of your data, optimized specifically for a given table. You can also control the size.
```python
data = connector.import_optimized_subset(
metadata=metadata,
main_table_name='users',
num_rows=5000
)
```
**Parameters**
* (required) `metadata`: A [Metadata](/sdv/integration/metadata.md) object that describes the data you want to import
* (required) `main_table_name`: A string containing the name of the most important table of your database. This table will generally represent the entity that is most critical to your application or business. It must be one of the tables listed in your metadata object.
* `num_rows`: The number of rows to sample from the main table. The size of every other table is automatically determined by its connection to the main table.
* `fixed_seed`: A boolean that controls the determinism of the random subset
* (default) `False`: Different random data will be imported every time you call the function
* `True`: The same data will be imported every time you import
* `verbose`: A boolean describing whether to print out details about the progress of the import
* (default) `True`: Print out the table names and number of rows being imported
* `False`: Do not print any details
**Output** A dictionary that maps each table name of your database (string) to the data, represented as a pandas DataFrame.
After importing the data and metadata, you are now ready to create an SDV synthesizer.
## Exporting synthetic data
Export synthetic data into a new database.
{% hint style="success" %}
**We recommend using the same connector as your import.** This connector object already knows about the specifics of your database schema. It will ensure that the exported data schema has the same format.
{% endhint %}
### ❖ set\_export\_config
Use this function to authenticate into the project and database you'd like to export to.
```python
connector.set_import_config(filepath='destination_db_config.yaml')
```
**Parameters**
* (required) `filepath`: A string with the filepath that contains your configuration options. For more information see section for [Configuration](/sdv/integration/db/integration.md).
**Output** (None)
### ❖ export
Use this function to export your synthetic data into a database
```python
connector.export(
data=synthetic_data,
mode='write',
verbose=True)
```
**Parameters**
* (required) `synthetic_data`: A dictionary that maps each table name to the synthetic data, represented as a pandas DataFrame
* `mode`: The mode of writing to use during the export
* (default) `'write'`: Write a new database from scratch. If the database or data already exists, then the function will error out.
* `'append'`: Append rows to existing tables in the database
* `'overwrite'`: Remove any existing tables in the database and replace them with this data
* `verbose`: A boolean describing whether to print out details about export
* (default) `True`: Print the details
* `False`: Do not print anything
**Output** (None) Your data will be written to the database and ready for use by your downstream application!
## FAQs
### Authentication & Credentials
Before using your connector, you will need to authenticate into the database. To do this, start by determining whether your account is a **user account** or a **service account**. Service accounts are typically made for non-human users. (For more details, [see the docs](https://cloud.google.com/iam/docs/best-practices-service-accounts).)
Authenticating a user account
If you are connecting a user account, we recommend using the Application Default Credentials (ADC).
**Prerequisites**: Run through these commands on your terminal (command line) before using Python.
1. To get started, install the Google CLI using [these instructions](https://cloud.google.com/sdk/docs/install#linux). Then run the following command on your terminal:
```
gcloud init
gcloud auth application-default login
```
This will prompt you to sign in, and then save the credentials onto your local machine in a pre-determined location ([see the docs](https://cloud.google.com/docs/authentication/application-default-credentials#personal)).
2. Next, run the following command in your terminal to generate a password to use for authentication. *Save this password.*
```
gcloud auth print-access-token
```
3. Finally run the following command to ensure you have access to the database. Fill in the each of the sections with your information.
```bash
gcloud alloydb users create --cluster= --region= --type=IAM_BASED
```
**Authentication in Python**: Now, you can use the Python library. The AI connector will automatically be able to find your file and authenticate you. Provide the following information when setting up your Python connector:
```python
connector.set_import_config(
schema_name='public',
auth={
'database': 'value', # required
'project_id': 'value', # required
'region': 'value', # required
'cluster_id': 'value', # required
'instance_id': 'value', # required
'ip_type': 'PUBLIC', # required: either 'PUBLIC' or 'PRIVATE'
'user': 'youremail@company.com', # required, your email used for authentication
'password': 'your-access-token', # required, from setp #2
}
)
```
Authenticating a service account
If you are connecting a service account, start by downloading a JSON credential file for the service account onto your machine. Follow the instructions in [these docs](https://developers.google.com/workspace/guides/create-credentials#create_credentials_for_a_service_account) to select your service account, add a key, and download the JSON file. (If you need help with this step, please contact your database admin.) Then follow the recommended approach below.
**Recommended approach**: When authenticating your AI connector, pass in the JSON filepath along with other necessary info, as shown below.
```python
connector.set_import_config(
auth={
'json_credentials_path': 'my_folder/credentials.json', # passs in JSON filepath
'database': 'value', # required
'project_id': 'value', # required
'region': 'value', # required
'cluster_id': 'value', # required
'instance_id': 'value', # required
},
schema_name='public'
)
```
**Alternative approach (environment variables)**: Alternatively, you can save the JSON filepath and project ID as global variables by typing the terminal commands below.
```bash
export GOOGLE_APPLICATION_CREDENTIALS=my_folder/credentials.json
export GOOGLE_CLOUD_PROJECT=my_project_id
```
Once you've run the above lines of code, your AI Connector can automatically locate the JSON file that just got saved and pull out the auth credentials from it. You don't have to specify this information anymore.
```python
connector.set_import_config(
auth={
'database': 'value', # required
'project_id': 'value', # required
'region': 'value', # required
'cluster_id': 'value', # required
'instance_id': 'value', # required
},
schema_name='public'
)
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.sdv.dev/sdv/integration/db/api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.