temp-python-sdk.mdx

title	Python SDK
sidebarTitle	Python SDK

Python SDK enables you to connect to the MindsDB server from Python using HTTP API. Read along to see how to install, test, and use the MindsDB Python SDK.

How to Install

To install the MindsDB Python SDK, run the below command:

pip install mindsdb_sdk

Here is the expected output:

**Alternative way of installation**

Instead of using the pip install mindsdb_sdk command, you can install it by cloning the Python SDK repository. Then you should create a virtual environment, install all dependencies from the requirements.txt file, and run tests as instructed below.

To test all the components, go to the project directory (mindsdb_sdk) and run the below command:

env PYTHONPATH=./ pytest

To generate the API documentation, run the below commands:

pip install sphinx
cd docs
make html

The documentation is generated in the docs/build/html folder.

How to Use

Connecting to MindsDB

You can connect to your local MindsDB server, MindsDB Cloud server, or MindsDB Pro server.

Here is how to connect to your local MindsDB server:

import mindsdb_sdk

# connects to the default port (47334) on localhost 
server = mindsdb_sdk.connect()

# connects to the specified host and port
server = mindsdb_sdk.connect('http://127.0.0.1:47334')

Here is how to connect to the MindsDB Cloud server:

import mindsdb_sdk

# option 1
server = mindsdb_sdk.connect(login='a@b.com', password='-')

# option 2
server = mindsdb_sdk.connect('https://cloud.mindsdb.com', login='a@b.com', password='-')

Here is how to connect to the MindsDB Pro server:

import mindsdb_sdk

server = mindsdb_sdk.connect('http://<YOUR_INSTANCE_IP>', login='a@b.com', password='-', is_managed=True)

Working with Databases

Use the create_database() method to connect data to MindsDB:

mysql_demo_db = server.create_database(
    engine = "mysql",
    name = "mysql_demo_db",
    connection_args = {
      "user": "user",
      "password": "MindsDBUser123!",
      "host": "db-demo-data.cwoyhfn6bzs0.us-east-1.rds.amazonaws.com",
      "port": "3306",
      "database": "public"
    }
)

Use the get_database() method to get a single database:

mysql_demo_db = server.get_database('mysql_demo_db')

Use the list_databases method to list all databases:

all_dbs = server.list_databases()

Working with Tables

Each table is stored in a database. Hence, we use the mysql_demo_db variable to run some of the commands below.

Use the list_tables() method to list all database tables:

mysql_demo_db.list_tables()

Use the get_table() method to fetch a table from the mysql_demo_db database:

my_table = mysql_demo_db.get_table('my_table')

Use the fetch() method to query for table's data:

my_table.filter(my_column='value')
my_table.limit(3)
my_table.fetch()

The filter() method filters the data based on the provided condition, and the limit() method limits the output rows.

Working with Projects

MindsDB uses projects to keep artifacts, such as models or views, separate according to what predictive task they solve. You can learn more about MindsDB projects here.

Use the get_project() method to get the default mindsdb project:

project = server.get_project()

Use the get_project() method to get other project:

project = server.get_project('project_name')

Use the create_project() method to create a new project:

server.create_project('project_name')

Use the drop_project() method to remove a project:

server.drop_project('project_name')

Use the list_projects() method to lists all available projects:

all_projects = server.list_projects()

Working with Models

Each model is stored in a project. Hence, we use the project variable to run some of the commands below.

Use the list_models() method to list all models contained in the project:

project.list_models()

Use the get_model() method to get an existing model:

my_model = project.get_model('my_model')

Or use the create_model() method to create and train a new model:

my_model = project.create_model (
    name = 'my_model',
    predict = 'target',
    query = my_table
)

Use the get_status() method to check the training status of the model:

my_model.get_status()

Use the predict() method to make predictions:

pred = my_model.predict(my_table.limit(10))

Above command returns predictions for the first 10 rows of the my_table table.

Use the drop_model() method to remove a model:

project.drop_model('my_model')

Working with Views

Each view is stored in a project. Hence, we use the project variable to run the commands below.

Use the create_view() method to create a view:

my_view = project.create_view(
    'view_name',
    mysql_demo_db.query('SELECT * FROM my_table LIMIT 100')
)

Use the list_views() method to list all views in a project:

project.list_views()

Use the drop_view() method to remove a view:

project.drop_view('view_name')

Working with Jobs

Each job is stored in a project. Hence, we use the project variable to run the commands below.

Use the create_job() method to create a job:

my_job = project.create_job(
    'job_name',
    'select * from models',
    repeat_str = '1 hour'
)

Use the list_jobs() method to list all jobs in a project:

project.list_jobs()

Use the drop_job() method to remove a job:

project.drop_job('job_name')

Example

Here is a sample code to create and train a model and make predictions:

# get the default project
project = server.get_project()

# prepare the training data
rentals_table = example_db.get_table('demo_data.home_rentals')
print('First 3 rows of home_rentals:')
print(rentals_table.limit(3).fetch())

# get all models
model_names = [i.name for i in  project.list_models()]

# create a model if it doesn't exist yet
if 'home_rentals_model' in model_names:
  print('home_rentals_model already exists. Returning existing model')
  home_rentals_model = project.get_model('home_rentals_model')

else:
  print('Creating home_rentals_model model')

  home_rentals_model = project.create_model(
      name='home_rentals_model',
      predict='rental_price',
      query = rentals_table
  )
  print('Created home_rentals_model successfully:')
  print(home_rentals_model)

  print('Waiting for model training to complete...please be patient')
  for i in range(400):
    print('.', end='')
    time.sleep(0.5)

  if home_rentals_model.get_status() not in ('generating', 'training'):
    print('\nFinished training home_rentals_model:')
    break

# get model's details      
print(home_rentals_model.data)

if home_rentals_model.get_status() == 'error':
  print('Something went wrong while training:')
  print(home_rentals_model.data['error'])

# make predictions
rentals_table_limit = rentals_table.limit(3)

print('Making prediction on the first 3 rows of home_rentals table')
ret = home_rentals_model.predict(rentals_table_limit)

print(ret[['number_of_rooms', 'number_of_bathrooms', 'rental_price']])

You can find the MindsDB Python SDK on the [PyPI webpage here](https://pypi.org/project/mindsdb-sdk/).

For more examples, visit the Google Colab Notebook here.