JavaScript SDK
The MindsDB JavaScript SDK allows you to unlock the power of machine learning right inside your web applications. We provide interfaces to perform most MindsDB operations, such as training and querying models, and connecting your own data sources to MindsDB. Read along to see how to install and use the MindsDB’s JavaScript SDK.
How to Install
To install the MindsDB JavaScript SDK, run the below command:
npm install --save mindsdb-js-sdk
Here is the expected output:
How to Use
Connecting to MindsDB
Before performing any operations, you must connect to MindsDB. By default, all operations will go through MindsDB Cloud REST APIs, but you can use a self-hosted version of MindsDB as well.
Local MindsDB
MindsDB Cloud
MindsDB Pro
Own Axios Instance
Here is how to connect to your local MindsDB server:
import MindsDB from 'mindsdb-js-sdk';
//alternative: const MindsDB = require("mindsdb-js-sdk").default;
try {
// No authentication needed for self-hosting
await MindsDB.connect({
host: 'http://127.0.0.1:47334'
});
console.log('connected');
} catch(error) {
// Failed to connect to local instance
console.log(error);
}
Please note that all methods that use await must be wrapped in an async function, like this:
(async() => {
try {
// No authentication needed for self-hosting
await MindsDB.connect({
host: 'http://127.0.0.1:47334'
});
console.log('connected');
} catch(error) {
// Failed to connect to local instance
console.log(error);
}
})();
Connecting a Database to MindsDB
Once you connected to MindsDB, you can connect to various data sources through MindsDB.
Here is how to connect our sample MySQL database:
const connectionParams = {
'user': 'user',
'port': 3306,
'password': 'MindsDBUser123!',
'host': 'db-demo-data.cwoyhfn6bzs0.us-east-1.rds.amazonaws.com',
'database': 'public'
}
try {
const mysqlDatabase = await MindsDB.Databases.createDatabase(
'mysql_datasource',
'mysql',
connectionParams);
console.log('connected a database');
} catch (error) {
// Couldn't connect to database
console.log(error);
}
First, we define the connection paramaters and then use the createDatabase function to connect a database.
Getting & Deleting a Database
Here is how to get an existing database and how to remove it:
try {
const db = await MindsDB.Databases.getDatabase('mysql_datasource');
console.log('got a database')
// Deleting a database
if (db) {
try {
await db.delete();
console.log('deleted a database');
} catch (error) {
// Couldn't delete a database
console.log(error);
}
}
} catch (error) {
// Couldn't connect to database
console.log(error);
}
Running SQL Queries
We prepare a variable that stores a query and use it as an argument to the runQuery function:
const query = `SELECT * FROM mysql_demo_db.amazon_reviews`;
try {
// Running a query
const queryResult = await MindsDB.SQL.runQuery(query);
// Printing output
console.log('output first two rows:');
if (queryResult.rows.length > 0) {
console.log(queryResult.rows[0]);
console.log(queryResult.rows[1]);
}
} catch (error) {
// Something went wrong sending the API request or executing the query
console.log(error);
}
If you want to use a variable within the SQL query, we recommend the below approach:
const user = 'raw_unsafe_username'
const query = `SELECT * FROM my_db.customer_data WHERE user=${mysql.escape(user)}`;
Getting Projects
Here is how to list all available projects:
const allProjects = await MindsDB.Projects.getAllProjects();
console.log('all projects:')
allProjects.forEach(p => {
console.log(p.name);
});
To learn more about MindsDB projects, visit our docs here.
Training & Querying Models
Training a model requires various parameters, depending on the model type. Here we present examples of regression and time series models.
Here are some useful links:
Let’s look at an example of how to create and train a simple regression model, and then, use it for making predictions.
// Defining training options
const regressionTrainingOptions = {
select: 'SELECT * FROM demo_data.home_rentals',
integration: 'example_db'
};
try {
// Creating and training a model
// The returned promise resolves when the model is created, NOT when training is actually complete
let homeRentalPriceModel = await MindsDB.Models.trainModel(
'home_rentals_model',
'rental_price',
'mindsdb',
regressionTrainingOptions);
console.log('created a model');
// Waiting for the training to be complete
while (homeRentalPriceModel.status !== 'complete' && homeRentalPriceModel.status !== 'error') {
homeRentalPriceModel = await MindsDB.Models.getModel('home_rentals_model', 'mindsdb');
}
// Checking model's status
console.log('Model status: ' + homeRentalPriceModel.status);
// Defining query options
const queryOptions = {
where: [
'sqft = 823',
'location = "good"',
'neighborhood = "downtown"',
'days_on_market = 10'
]
}
// Querying for a single prediction
const rentalPricePrediction = await homeRentalPriceModel.query(queryOptions);
console.log('Predicted value:');
console.log(rentalPricePrediction.value);
console.log('Prediction insights:');
console.log(rentalPricePrediction.explain);
console.log('Input data:');
console.log(rentalPricePrediction.data);
} catch (error) {
// Something went wrong training or querying
console.log(error);
}
As time series models require more parameters, let’s go over an example of how to create and train a time series model, and then, use it for making batch predictions.
// Defining training options
const timeSeriesTrainingOptions = {
integration: 'example_db',
select: 'SELECT * FROM demo_data.house_sales',
orderBy: 'saledate',
groupBy: 'bedrooms',
window: 8,
horizon: 4
}
try {
// Creating and training a model
let houseSalesForecastModel = await MindsDB.Models.trainModel(
'house_sales_model',
'ma',
'mindsdb',
timeSeriesTrainingOptions);
console.log('created a model');
// Waiting for the training to be complete
while (houseSalesForecastModel.status !== 'complete' && houseSalesForecastModel.status !== 'error') {
houseSalesForecastModel = await MindsDB.Models.getModel('house_sales_model', 'mindsdb');
}
// Checking model's status
console.log('Model status: ' + houseSalesForecastModel.status);
// Describing a model
const modelDescription = await houseSalesForecastModel.describe();
console.log('Model description:');
console.log(modelDescription);
// Defining query options
const queryOptions = {
// Join model to this data source
join: 'example_db.demo_data.house_sales',
// When using batch queries, the 't' alias is used for the joined data source ('t' is short for training/test)
// The 'm' alias is used for the trained model to be queried
where: ['t.saledate > LATEST', 't.bedrooms = 2'],
limit: 4
}
// Querying for batch predictions
const rentalPriceForecasts = await houseSalesForecastModel.batchQuery(queryOptions);
console.log('Batch predictions:');
rentalPriceForecasts.forEach(f => {
console.log(f.value);
console.log(f.explain);
console.log(f.data);
})
} catch (error) {
// Something went wrong training or predicting.
console.log(error);
}
Retraining a Model
Models require to be retrained regularly. You can learn more about it here.
In the following example, we get an existing model and retrain it if its update status is available.
// Getting an existing model
const homeRentalPriceModel = await MindsDB.Models.getModel('home_rentals_model', 'mindsdb');
// Checking the status and retraining a model if required
if (homeRentalPriceModel.updateStatus === 'available') {
try {
// For custom retraining: homerentalPriceModel.retrain('example_db', trainingOptions);
await homeRentalPriceModel.retrain();
console.log('retrained a model');
} catch (error) {
// Something went wrong with retraining
console.log(error);
}
}
You can find full training options here.
Finetuning a Model
You may want to finetune your model with a specific dataset. You can learn more about it here.
Here is how you can finetune, or adjust, a model:
// Getting a model
const homeRentalPriceModel = await MindsDB.Models.getModel('home_rentals_model', 'mindsdb');
console.log('got a model');
// Defining data used to finetune a model
const adjustSelect = 'SELECT * FROM demo_data.home_rentals WHERE days_on_market >= 10';
//const params = { 'key' : 'value' }
try {
// Finetuning/adjusting a model with the specified dataset
await homeRentalPriceModel.adjust({
integration: 'example_db',
select: adjustSelect
//using: params
});
console.log('finetuned a model');
} catch (error) {
// Something went wrong adjusting
console.log(error);
}
You can find full adjust options here.
Creating Views
Here is how to create views:
// Defining a query
const viewSelect = `SELECT t.sqft, t.location, m.rental_price
FROM mysql_demo_db.home_rentals as t
JOIN mindsdb.home_rentals_model as m`;
try {
// Creating a view
const predictionsView = await MindsDB.Views.createView(
'predictions_view',
'mindsdb',
viewSelect);
console.log('created a view');
} catch (error) {
// Something went wrong creating the view
console.log(error);
}
First, we define a query based on which the view is created. Then we use the createView() function with arguments including the view name, the project name where the view is to be created, and the query.