### Install MindSQL using pip

Source: https://github.com/mindinventory/mindsql/wiki/Home

Use this command to install the MindSQL package from PyPI.

```shell
pip install mindsql
```

--------------------------------

### Initialize MindSQLCore Instance

Source: https://github.com/mindinventory/mindsql/wiki/🚀-Quickstart

Create a MindSQLCore instance by specifying the LLM, vector store, and database components. This example uses Google GenAi, ChromaDB, and Sqlite. Ensure your API key is configured.

```python
from mindsql.core import MindSQLCore
from mindsql.databases import Sqlite
from mindsql.llms import GoogleGenAi
from mindsql.vectorstores import ChromaDB

# Add Your Configurations
config = {"api_key": "YOUR-API-KEY"}

# Create MindSQLCore Instance
minds = MindSQLCore(
    llm=GoogleGenAi(config=config),
    vectorstore=ChromaDB(),
    database=Sqlite()
)
```

--------------------------------

### Retrieve Data and SQL Query

Source: https://github.com/mindinventory/mindsql/wiki/💬-ask_db

Query the system with a specific question to retrieve both the SQL query generated by the system and the resulting data. Set visualize to False to only get data.

```python
result = ask_db(question="What is the average salary of employees?", connection=my_connection, table_names=["employees"], visualize=False)
```

--------------------------------

### Example JSON Structure for Bulk Data

Source: https://github.com/mindinventory/mindsql/wiki/📑-Index

This JSON structure defines the format for question-SQL pairs used in bulk data addition, where each entry contains a 'Question' and its corresponding 'SQLQuery'.

```json
[
  {
    "Question": "What is the average salary?",
    "SQLQuery": "SELECT AVG(salary) FROM employees"
  },
  {
    "Question": "Retrieve the latest order for each customer, including customer details and order date.",
    "SQLQuery": "SELECT Customers.CustomerID, Customers.ContactName, Orders.OrderID, MAX(Orders.OrderDate) AS LatestOrderDate FROM Customers LEFT JOIN Orders ON Customers.CustomerID = Orders.CustomerID GROUP BY Customers.CustomerID, Customers.ContactName, Orders.OrderID;"
  },
  {
    "Question": "List suppliers who supply both beverages and dairy products.",
    "SQLQuery": "SELECT DISTINCT Suppliers.SupplierID, Suppliers.SupplierName FROM Suppliers INNER JOIN Products ON Suppliers.SupplierID = Products.SupplierID INNER JOIN Categories ON Products.CategoryID = Categories.CategoryID WHERE Categories.CategoryName IN ('Beverages', 'Dairy Products') GROUP BY Suppliers.SupplierID, Suppliers.SupplierName HAVING COUNT(DISTINCT Categories.CategoryID) = 2;"
  }
]
```

--------------------------------

### Initialize MindSQL Core and Interact with Database

Source: https://github.com/mindinventory/mindsql/blob/master/README.md

Initialize MindSQLCore with your chosen LLM, vector store, and database. This snippet demonstrates connecting to a database, indexing DDL statements, indexing question-sql pairs, and querying the database with visualization.

```python
# !pip install mindsql

from mindsql.core import MindSQLCore
from mindsql.databases import Sqlite
from mindsql.llms import GoogleGenAi
from mindsql.vectorstores import ChromaDB

# Add Your Configurations
config = {"api_key": "YOUR-API-KEY"}

# Choose the Vector Store. LLM and DB You Want to Work With And
# Create MindSQLCore Instance With Configured Llm, Vectorstore, And Database
minds = MindSQLCore(
    llm=GoogleGenAi(config=config),
    vectorstore=ChromaDB(),
    database=Sqlite()
)

# Create a Database Connection Using The Specified URL
connection = minds.database.create_connection(url="YOUR_DATABASE_CONNECTION_URL")

# Index All Data Definition Language (DDL) Statements in The Specified Database Into The Vectorstore
minds.index_all_ddls(connection=connection, db_name='NAME_OF_THE_DB')

# Index Question-Sql Pair in Bulk From the Specified Example Path
minds.index(bulk=True, path="your-qsn-sql-example.json")

# Ask a Question to The Database And Visualize The Result
response = minds.ask_db(
    question="YOUR_QUESTION",
    connection=connection,
    visualize=True
)

# Extract And Display The Chart From The Response
chart = response["chart"]
chart.show()

# Close The Connection to Your DB
connection.close()
```

--------------------------------

### Add Documentation String to Index

Source: https://github.com/mindinventory/mindsql/wiki/📑-Index

Provide context-specific information, such as business logic or industry terminology, to help the system understand the domain and accurately interpret user queries.

```python
index(documentation="The salaries of employees are in USD($)")
```

--------------------------------

### Create Database Connection

Source: https://github.com/mindinventory/mindsql/wiki/🚀-Quickstart

Establish a connection to your database using the provided URL. This connection object is then used for subsequent database operations.

```python
# Create a Database Connection Using The Specified URL
connection = minds.database.create_connection(url="YOUR_DATABASE_CONNECTION_URL")
```

--------------------------------

### Execute Database Query with Visualization

Source: https://github.com/mindinventory/mindsql/wiki/🚀-Quickstart

Execute database queries using the ask_db method. This method can optionally generate charts from the query results if visualize is set to True. Specify the question, connection, and optionally table names.

```python
response = minds.ask_db(question="YOUR-QUESTION", connection=conn, visualize=True, table_names=['TABLE_NAME'])
```

--------------------------------

### Bulk Data Addition using Index

Source: https://github.com/mindinventory/mindsql/wiki/📑-Index

Efficiently integrate multiple question-SQL pairs from an external JSON file by using the index method with the `bulk=True` flag and specifying the file path.

```python
index(bulk=True, path="data.json")
```

--------------------------------

### Add Question-SQL Pair to Index

Source: https://github.com/mindinventory/mindsql/wiki/📑-Index

Use this to directly instruct the system on how to interpret a specific user query by associating a question with its corresponding SQL query.

```python
index(
    question="What is the average salary?", 
    sql="SELECT AVG(salary) FROM employees"
)
```

--------------------------------

### Commit Changes

Source: https://github.com/mindinventory/mindsql/blob/master/CONTRIBUTING.md

Commit your changes with a clear and descriptive message.

```bash
git commit -am 'Add descriptive commit message'
```

--------------------------------

### Create a New Branch

Source: https://github.com/mindinventory/mindsql/blob/master/CONTRIBUTING.md

Create a new branch for your contributions based on the 'master' branch.

```bash
git checkout -b your-branch-name master
```

--------------------------------

### Visualize Data with Plotly Charts

Source: https://github.com/mindinventory/mindsql/wiki/💬-ask_db

Query the system for data and visualize the results using plotly charts. Set visualize to True to generate charts.

```python
result = ask_db(question="Show monthly sales trend for the past year.", connection=my_connection, visualize=True)
chart = result["chart"]
```

--------------------------------

### Clone MindSQL Repository

Source: https://github.com/mindinventory/mindsql/blob/master/CONTRIBUTING.md

Clone the MindSQL repository to your local machine after forking it.

```bash
git clone https://github.com/{YourUsername}/MindSQL.git
```

--------------------------------

### Push Changes to Fork

Source: https://github.com/mindinventory/mindsql/blob/master/CONTRIBUTING.md

Push your committed changes to your fork on GitHub.

```bash
git push origin your-branch-name
```

--------------------------------

### ask_db Method

Source: https://github.com/mindinventory/mindsql/wiki/💬-ask_db

The ask_db method allows users to query the database using natural language. It can return the generated SQL query, the DataFrame result, a natural language response, and optionally, charts or visualizations.

```APIDOC
## ask_db Method

### Description
This method serves as the primary interface for querying the system and obtaining insights from the underlying data using natural language. It translates user questions into SQL queries, executes them against the database, and returns the results.

### Method Signature
```python
ask_db(question: str, connection: any, table_names: list = None, visualize: bool = False)
```

### Parameters
#### Parameters
* **question** (str): Specifies the question or query to be submitted to the system for processing.
* **connection** (any): The connection object to the database, required for executing SQL queries.
* **table_names** (list): Optional parameter specifying the list of tables relevant to the query. If provided, MindSQL will use these table names to get relevant DDL instead of retrieving them from the vectorstore.
* **visualize** (bool): Indicates whether to visualize the results using plotly charts. Defaults to False.

### Returns
* **sql** (str): The SQL Query generated by the LLM based on user's question.
* **sql_result** (DataFrame): The DataFrame result after executing the generated SQL query.
* **response** (str): A natural language response crafted by the LLM based on the retrieved DataFrame.
* **chart** (any): Charts or visualizations generated based on the data retrieved, if `visualize` is set to True.

### Examples
#### Retrieving Data and SQL Query
```python
result = ask_db(question="What is the average salary of employees?", connection=my_connection, table_names=["employees"], visualize=False)
```

#### Visualizing Data
```python
result = ask_db(question="Show monthly sales trend for the past year.", connection=my_connection, visualize=True)
chart = result["chart"]
```

### Notes
* Users must provide a valid database connection object.
* The `table_names` parameter is optional. If not provided, the system will attempt to infer relevant tables from the vectorstore.
* Setting `visualize` to `True` enables the generation of plotly charts for the query results.
```

--------------------------------

### Show Generated Chart

Source: https://github.com/mindinventory/mindsql/wiki/🚀-Quickstart

Visualize the data from the query results by accessing and displaying the chart object returned in the response.

```python
chart = response["chart"]
chart.show()
```

--------------------------------

### Index All DDL Statements

Source: https://github.com/mindinventory/mindsql/wiki/🚀-Quickstart

Use the index_all_ddls method to retrieve and index all Data Definition Language (DDL) statements from the specified database into the vector store. Requires an active database connection and the database name.

```python
# Index All Data Definition Language (DDL) Statements in The Specified Database Into The Vectorstore
minds.index_all_ddls(connection=connection, db_name='NAME_OF_THE_DB')
```

--------------------------------

### Add DDL Statement to Index

Source: https://github.com/mindinventory/mindsql/wiki/📑-Index

Incorporate Data Definition Language (DDL) statements to define the structure of database objects, providing essential schema information for effective query interpretation.

```python
index(ddl="CREATE TABLE employees (id INT, name VARCHAR(50), salary FLOAT)")
```

--------------------------------

### Close Database Connection

Source: https://github.com/mindinventory/mindsql/wiki/🚀-Quickstart

Close the database connection when all operations are completed to free up resources.

```python
conn.close()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.