+++
title = "Quickstart"
weight = 2
template = "docs/getting-started.html"
aliases = ["/docs/creating-your-first-index", "/docs/get-started/create-your-first-index/"]

[extra]
weight = 2
+++

{% gs_header() %}
Get up and running with Bonsai in under 10 minutes. Create an account, provision a cluster, index your first
document, and run a search query. Everything you need to get up-and-running with Bonsai.io for a production-ready 
Elasticsearch/OpenSearch setup.
{% end %}

<!-- Section 1: Create an Account -->
{% gs_section(number="1", title="Create an Account", intro="Before you can create indexes and run queries, you'll need a
Bonsai account.") %}

{% gs_step(title="Sign up at bonsai.io") %}
Visit <a href="https://app.bonsai.io/signup" class="gs-link" target="_blank" rel="noopener">app.bonsai.io/signup</a> to create your account.
{% end %}
{{ image(src="signup-page.png", alt="Bonsai sign-up page", full=true, resize_width=1200) }}

{% gs_step(title="Verify your email") %}
After signing up, check your inbox and verify your email address before continuing.
{% end %}
{{ image(src="email-verification-pending.png", alt="Email verification pending", automatically_determine_ratio=true, resize_width=800) }}

{% gs_step(title="Continue to dashboard") %}
Once verified, click to continue and your first cluster will begin provisioning automatically.
{% end %}
{{ image(src="email-verified.png", alt="Email verified - continue to dashboard", automatically_determine_ratio=true, resize_width=800) }}

{% end %}

{{ gs_divider() }}

<!-- Section 2: Create a Cluster -->
{% gs_section(number="2", title="Create a Cluster", alt="true", intro="Your first cluster provisions automatically when
you sign up - manual configuration needed. Bonsai handles the infrastructure, security, and maintenance so you can
focus on building search features. Deploy on **AWS** or **GCP** in the region closest to your users.") %}

{% gs_step(title="Cluster provisioning") %}
Your cluster will provision in seconds. You may briefly see this screen while it spins up.
{% end %}
{{ image(src="cluster-provisioning.png", alt="Cluster provisioning in progress", full=true, resize_width=1200) }}

{% gs_step(title="Cluster ready") %}
Once provisioned, you'll see your Bonsai dashboard with your cluster ready to use.
{% end %}
{{ image(src="cluster-ready.png", alt="Cluster ready - Bonsai dashboard", full=true, resize_width=1200) }}

{% toast(type="success") %}Your cluster is ready! Now let's get your connection details.{% end %}

{% end %}

{{ gs_divider() }}

<!-- Section 3: Get Your Connection Details -->
{% gs_section(number="3", title="Get Your Connection Details", intro="Every Bonsai cluster has a unique URL that
includes authentication credentials. This single URL is all you need to connect from any client library, CLI tool, or
application.") %}

{% gs_verify_item(title="Copy Your Credentialed URL", icon="link", full_width="true") %}
<li>Open your <a href="https://app.bonsai.io" class="gs-link" target="_blank" rel="noopener">Bonsai dashboard</a></li>
<li>Select your cluster</li>
<li>On the <strong>"Connect"</strong> dropdown, copy the full URL (includes username and password)</li>
{% end %}

{{ image(src="cluster-credentials.png", alt="Cluster credentials - Bonsai dashboard", full=true, automatically_determine_ratio=true, resize_width=1200) }}

{% toast(type="success") %}You now have a URL like <code>https://user:pass@cluster-slug.bonsai.io</code>{% end %}

{% admonition(type="info", title="Need to add/change credentials?") %}

- Navigate to the **Access** tab in your cluster settings
- Paid plans allow you to create and manage multiple access credentials
- Sandbox clusters have credentials embedded in the URL by default
- [Full credentials management guide](/docs/features/credential-management/)
  {% end %}

{% end %}

{{ gs_divider() }}

<!-- Section 4: Index Your First Document -->
{% gs_section(number="4", title="Index Your First Document", alt="true", intro="Indexing is how you add data to your
cluster. Each `document` is a JSON object with fields you define. Elasticsearch/OpenSearch will automatically make it
searchable. For this quick start guide, we've included some sample interfaces, but you can interact with OpenSearch with 
virtually any programming language!") %}

{% admonition(type="tip", title="Explore Bonsai with Sample Data") %}
Want to experiment without creating your own data? Load the Flights dataset in OpenSearch Dashboards:

1. Open OpenSearch Dashboards (link in your Bonsai dashboard)
2. Click **Add sample data**
3. Select **Sample flight data** and click **Add data**

<a href="https://opensearch.org/docs/latest/dashboards/quickstart/#adding-sample-data" class="gs-link" target="_blank" rel="noopener">OpenSearch Sample Data Documentation</a>
{% end %}

{% gs_tabs(variant="interface", group="interface-index") %}
{% gs_tab_list() %}
{{ gs_tab_trigger(id="console", label="Bonsai Console", icon="monitor", active="true") }}
{{ gs_tab_trigger(id="dashboards", label="OpenSearch Dashboards", icon="cube") }}
{{ gs_tab_trigger(id="curl", label="curl / API", icon="terminal") }}
{{ gs_tab_trigger(id="typescript", label="TypeScript", icon="code") }}
{% end %}
{% gs_tab_panel(id="console", active="true") %}
{% gs_interface_steps() %}
<li>Open your <a href="https://app.bonsai.io" class="gs-link" target="_blank" rel="noopener">Bonsai Console</a></li>
<li>Navigate to your cluster's <strong>Console</strong> tab</li>
<li>In the query editor, enter:</li>
{% end %}

{% gs_code() %}

```json
PUT /my-index/_doc/1
{
  "title": "Hello Bonsai",
  "message": "My first document"
}
```

{% end %}

{{ gs_step_note(text="Click the <strong>Play</strong> button or press Ctrl+Enter to run the query.") }}

{% gs_expected_result() %}

```json
{
  "result": "created",
  "_index": "my-index",
  "_id": "1"
}
```

{% end %}
{% toast(type="success") %}Success: Document created{% end %}
{% admonition(type="warning", title="Error 401? Solutions") %}

- Verify credentials in Access tab
- Check URL format includes user:pass
- [HTTP 401 troubleshooting](/docs/troubleshooting/http-errors/http-401-authorization-required/)
  {% end %}
  {% end %}
  {% gs_tab_panel(id="dashboards") %}
  {% gs_interface_steps() %}

<li>Open OpenSearch Dashboards (link in your Bonsai dashboard)</li>
<li>Go to <strong>Dev Tools</strong> in the left sidebar</li>
<li>In the console, enter:</li>
{% end %}

{% gs_code() %}

```json
PUT /my-index/_doc/1
{
  "title": "Hello Bonsai",
  "message": "My first document"
}
```

{% end %}

{{ gs_step_note(text="Click the <strong>Play</strong> button (green triangle) to execute the request.") }}

{% gs_expected_result() %}

```json
{
  "result": "created",
  "_index": "my-index",
  "_id": "1"
}
```

{% end %}
{% toast(type="success") %}Success: Document created{% end %}
{% admonition(type="info", title="Can't find Dev Tools?") %}

- Look under the hamburger menu (three lines) in the top-left corner
- Select "Dev Tools" from the sidebar
- [Bonsai Console guide](/docs/features/console/)
  {% end %}
  {% end %}
  {% gs_tab_panel(id="curl") %}
  {% gs_interface_steps(intro="Run this command in your terminal:") %}

```bash
curl -X PUT "$BONSAI_URL/my-index/_doc/1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello Bonsai",
    "message": "My first document"
  }'
```

{{ gs_step_note(text="Make sure <code>$BONSAI_URL</code> includes your credentials: <code>https://user:pass@cluster-slug.bonsai.io</code>") }}
{% end %}

{% gs_expected_result() %}

```json
{
  "result": "created",
  "_index": "my-index",
  "_id": "1",
  "_version": 1,
  "_primary_term": 1,
  "_seq_no": 0
}
```

{% end %}
{% toast(type="success") %}Success: Document created{% end %}
{% admonition(type="warning", title="Error 401? Solutions") %}

- Check that your URL includes username:password before the hostname
- Verify the credentials match those in Access tab
- [HTTP 401 troubleshooting](/docs/troubleshooting/http-errors/http-401-authorization-required/)
  {% end %}
  {% end %}
  {% gs_tab_panel(id="typescript") %}

<p>For a complete TypeScript example using NestJS, see our guide:</p>
{{ gs_button(href="https://bonsai.io/blog/supercharge-your-nestjs-app-with-hosted-search/", label="NestJS + Bonsai Guide", variant="primary", external="true") }}
{{ gs_step_note(text="This guide demonstrates creating an index and seeding it with data in a NestJS application.") }}
{% end %}
{% end %}

{% end %}

{{ gs_divider() }}

<!-- Section 5: Run Your First Search Query -->
{% gs_section(number="5", title="Run Your First Search Query", intro="Now for the payoff: run a search query against
your indexed data. The `match` query finds documents containing your search terms, with results ranked by
relevance.") %}

{% gs_tabs(variant="interface", group="interface-search") %}
{% gs_tab_list() %}
{{ gs_tab_trigger(id="console", label="Bonsai Console", icon="monitor", active="true") }}
{{ gs_tab_trigger(id="dashboards", label="OpenSearch Dashboards", icon="cube") }}
{{ gs_tab_trigger(id="curl", label="curl / API", icon="terminal") }}
{% end %}
{% gs_tab_panel(id="console", active="true") %}
{% gs_interface_steps() %}
<li>In your cluster's <strong>Console</strong> tab, enter:</li>
{% end %}

{% gs_code() %}

```json
GET /my-index/_search
{
  "query": {
    "match": {
      "title": "hello"
    }
  }
}
```

{% end %}

{{ gs_step_note(text="Click the <strong>Play</strong> button or press Ctrl+Enter to run the query.") }}

{% gs_expected_result() %}

```json
{
  "hits": {
    "total": {
      "value": 1
    },
    "hits": [
      {
        "_source": {
          "title": "Hello Bonsai",
          "message": "My first document"
        }
      }
    ]
  }
}
```

{% end %}
{% toast(type="success") %}Success: You've completed your first search!{% end %}
{% admonition(type="info", title="No results?") %}

- Make sure you indexed the document first
- Check that the index name matches exactly
- Wait a moment for indexing to complete
- [Connection troubleshooting](/docs/troubleshooting/connection-issues/)
  {% end %}
  {% end %}
  {% gs_tab_panel(id="dashboards") %}
  {% gs_interface_steps() %}

<li>In <strong>Dev Tools</strong>, enter:</li>
{% end %}

{% gs_code() %}

```json
GET /my-index/_search
{
  "query": {
    "match": {
      "title": "hello"
    }
  }
}
```

{% end %}

{{ gs_step_note(text="Alternatively, use the <strong>Discover</strong> tab to visually browse and search your indexed
data.") }}

{% gs_expected_result() %}

```json
{
  "hits": {
    "total": {
      "value": 1
    },
    "hits": [
      {
        "_source": {
          "title": "Hello Bonsai",
          "message": "My first document"
        }
      }
    ]
  }
}
```

{% end %}
{% toast(type="success") %}Success: You've completed your first search!{% end %}
{% admonition(type="tip", title="Want to use Discover?") %}

- First create an index pattern: Management > Index Patterns > Create
- Use "my-index" as the pattern name
- [Using Kibana with Bonsai](/docs/features/using-kibana-with-bonsai/)
  {% end %}
  {% end %}
  {% gs_tab_panel(id="curl") %}
  {% gs_interface_steps(intro="Run this command in your terminal:") %}

```bash
curl -X GET "$BONSAI_URL/my-index/_search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": { "title": "hello" }
    }
  }'
```

{% end %}

{% gs_expected_result() %}

```json
{
  "took": 5,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.2876821,
    "hits": [
      {
        "_index": "my-index",
        "_id": "1",
        "_score": 0.2876821,
        "_source": {
          "title": "Hello Bonsai",
          "message": "My first document"
        }
      }
    ]
  }
}
```

{% end %}
{% toast(type="success") %}Success: You've completed your first search!{% end %}
{% admonition(type="info", title="No results?") %}

- Check that the index name matches
- Wait a moment for indexing to complete
- Verify your BONSAI_URL environment variable
- [Connection troubleshooting](/docs/troubleshooting/connection-issues/)
  {% end %}
  {% end %}
  {% end %}

{% end %}

{{ gs_divider() }}

<!-- Section 6: Integrate with Your App -->
{% gs_section(number="6", title="Integrate with Your App", alt="true", intro="Ready to add search to your application?
Use our official client libraries to connect your codebase to Bonsai. Each library handles authentication, connection
pooling, and retries automatically.") %}


{% admonition(type="info", title="Do it all in your favorite language!") %}
You can do everything we've discussed above in your favorite language, too - Create indexes, add documents, execute complex queries, and more!

The examples above referencing cURL, and the Bonsai console are intended to help you ramp-up to your first-query;
don't feel limited by them!
{% end %}

{% gs_tabs(variant="interface", group="language-tabs") %}
{% gs_tab_list() %}
{{ gs_tab_trigger(id="nodejs", label="Node.js", icon="layers", active="true") }}
{{ gs_tab_trigger(id="python", label="Python", icon="layers") }}
{{ gs_tab_trigger(id="ruby", label="Ruby", icon="layers") }}
{{ gs_tab_trigger(id="go", label="Go", icon="layers") }}
{{ gs_tab_trigger(id="java", label="Java", icon="layers") }}
{{ gs_tab_trigger(id="php", label="PHP", icon="layers") }}
{% end %}
{% gs_tab_panel(id="nodejs", active="true", process_markdown="true") %}
{{ gs_install(command="npm install @opensearch-project/opensearch") }}

```javascript
const {Client} = require("@opensearch-project/opensearch");

// BONSAI_URL includes embedded credentials (https://user:pass@host)
const client = new Client({
    node: process.env.BONSAI_URL,
});

// Test the connection
(async () => {
    const health = await client.cluster.health();
    console.log("Cluster health:", health.body.status);
})();
```

{% gs_button_group() %}{{ gs_button(href="/docs/connecting/node-js/", label="View Node.js Guide", icon="book", variant="primary") }}{{ gs_button(href="https://docs.opensearch.org/latest/clients/javascript/index/", label="API Reference", icon="code", variant="secondary") }}{% end %}
{% end %}
{% gs_tab_panel(id="python", process_markdown="true") %}
{{ gs_install(command="pip install opensearch-py") }}

```python
from opensearchpy import OpenSearch
import os

# BONSAI_URL includes embedded credentials (https://user:pass@host)
client = OpenSearch(os.environ['BONSAI_URL'])

# Test the connection
health = client.cluster.health()
print(f"Cluster health: {health['status']}")
```

{% gs_button_group() %}{{ gs_button(href="/docs/connecting/python/", label="View Python Guide", icon="book", variant="primary") }}{{ gs_button(href="https://docs.opensearch.org/latest/clients/python-low-level/", label="API Reference", icon="code", variant="secondary") }}{% end %}
{% end %}
{% gs_tab_panel(id="ruby", process_markdown="true") %}
{{ gs_install(command="bundle add searchkick") }}

```ruby
# config/initializers/searchkick.rb
# Searchkick uses ELASTICSEARCH_URL by convention
ENV['ELASTICSEARCH_URL'] = ENV['BONSAI_URL']

# app/models/product.rb
class Product < ApplicationRecord
  searchkick
end

# Reindex your data
Product.reindex

# Search
results = Product.search("hello")
puts "Found #{results.count} results"
```

{% gs_button_group() %}{{ gs_button(href="/docs/connecting/ruby-on-rails-searchkick/", label="View Searchkick Guide", icon="book", variant="primary") }}{{ gs_button(href="https://github.com/ankane/searchkick", label="Searchkick on GitHub", icon="code", variant="secondary", external="true") }}{% end %}
{% end %}
{% gs_tab_panel(id="go", process_markdown="true") %}
{{ gs_install(command="go get github.com/opensearch-project/opensearch-go/v4") }}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/opensearch-project/opensearch-go/v4"
    "github.com/opensearch-project/opensearch-go/v4/opensearchapi"
)

func main() {
    client, err := opensearchapi.NewClient(opensearchapi.Config{
        Client: opensearch.Config{
            Addresses: []string{os.Getenv("BONSAI_URL")},
            Username:  os.Getenv("BONSAI_USERNAME"),
            Password:  os.Getenv("BONSAI_PASSWORD"),
        },
    })
    if err != nil {
        log.Fatalf("Error creating client: %s", err)
    }

    res, err := client.Cluster.Health(context.Background(), nil)
    if err != nil {
        log.Fatalf("Error getting health: %s", err)
    }
    fmt.Println("Cluster health:", res.Status)
}
```

{% gs_button_group() %}{{ gs_button(href="https://docs.opensearch.org/latest/clients/go/", label="API Reference", icon="code", variant="secondary") }}{% end %}
{% end %}
{% gs_tab_panel(id="java", process_markdown="true") %}
{{ gs_install(label="Add to pom.xml:", command="org.opensearch.client:opensearch-java") }}

```java
import org.apache.hc.client5.http.auth.AuthScope;
import org.apache.hc.client5.http.auth.UsernamePasswordCredentials;
import org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider;
import org.apache.hc.core5.http.HttpHost;
import org.opensearch.client.opensearch.OpenSearchClient;
import org.opensearch.client.transport.httpclient5.ApacheHttpClient5TransportBuilder;

import java.net.URI;

String connString = System.getenv("BONSAI_URL");
URI connUri = URI.create(connString);
String[] auth = connUri.getUserInfo().split(":");

BasicCredentialsProvider cp = new BasicCredentialsProvider();
cp.setCredentials(new AuthScope(connUri.getHost(), connUri.getPort()),
    new UsernamePasswordCredentials(auth[0], auth[1].toCharArray()));

HttpHost host = new HttpHost(connUri.getScheme(), connUri.getHost(), connUri.getPort());
OpenSearchClient client = new OpenSearchClient(
    ApacheHttpClient5TransportBuilder.builder(host)
        .setHttpClientConfigCallback(b -> b.setDefaultCredentialsProvider(cp))
        .build());
```

{% gs_button_group() %}{{ gs_button(href="/docs/connecting/java/", label="View Java Guide", icon="book", variant="primary") }}{{ gs_button(href="https://docs.opensearch.org/latest/clients/java/", label="API Reference", icon="code", variant="secondary") }}{% end %}
{% end %}
{% gs_tab_panel(id="php", process_markdown="true") %}
{{ gs_install(command="composer require opensearch-project/opensearch-php guzzlehttp/guzzle") }}

```php
<?php
require 'vendor/autoload.php';

// Parse BONSAI_URL for connection details
$url = parse_url(getenv('BONSAI_URL'));
$baseUri = $url['scheme'] . '://' . $url['host'] . (isset($url['port']) ? ':' . $url['port'] : '');

$client = (new \OpenSearch\GuzzleClientFactory())->create([
    'base_uri' => $baseUri,
    'auth' => [$url['user'], $url['pass']],
]);

// Test the connection
$health = $client->cluster()->health();
echo "Cluster health: " . $health['status'];
```

{% gs_button_group() %}{{ gs_button(href="/docs/connecting/php/", label="View PHP Guide", icon="book", variant="primary") }}{{ gs_button(href="https://docs.opensearch.org/latest/clients/php/", label="API Reference", icon="code", variant="secondary") }}{% end %}
{% end %}
{% end %}

{% end %}

{{ gs_divider() }}

{% gs_next_steps(title="Next Steps", subtitle="Ready to take your new cluster to production? Check out these resources.") %}
{% gs_next_card(href="/docs/get-started/production-guide/", title="Production Guide", icon="checkmark", link_text="
Continue setup", primary="true") %}
Prepare your cluster for production traffic with capacity planning, high availability, and security best practices.
{% end %}
{% gs_next_card(href="/docs/platform/core-concepts/", title="Core
Concepts", icon="book", link_text="Learn more") %}
Deepen your understanding of nodes, clusters, indices, shards, and mappings to make better architectural decisions.
{% end %}
{% gs_next_card(href="/docs/features/credential-management/",
title="Credential Management", icon="lock", link_text="Secure your cluster") %}
Set up read-only credentials, rotate keys, and implement role-based access control for your applications.
{% end %}
{% gs_next_card(href="/docs/features/dashboard-metrics/", title="
Dashboard Metrics", icon="chart", link_text="Start monitoring") %}
Monitor cluster health, track performance, and troubleshoot issues using the Bonsai built-in metrics dashboard.
{% end %}
{% end %}