Expected time: 30 minutes

:::callout{intent="info" title="What you will learn"}
This quickstart shows you how to combine Weaviate Cloud and the **Weaviate Embeddings** service to:

1. Set up a Weaviate Cloud instance. (10 minutes)
2. Add and vectorize your data using Weaviate Embeddings. (10 minutes)
3. Perform a semantic (vector) search and hybrid search. (10 minutes)

```mermaid
flowchart LR
    %% Define nodes with white backgrounds and darker borders
    A1["Create a new<br> cluster"] --> A2["Install client<br> library"]
    A2 --> A3["Connect to<br> Weaviate Cloud"]
    A3 --> B1["Configure the<br> vectorizer"]
    B1 --> B2["Import<br> objects"]
    B2 --> C1["Semantic (vector)<br> search"]

    %% Group nodes in subgraphs with brand colors
    subgraph sg1 ["1\. Setup"]
        A1
        A2
        A3
    end

    subgraph sg2 ["2\. Populate"]
        B1
        B2
    end

    subgraph sg3 ["3\. Query"]
        C1
    end

    %% Style nodes with white background and darker borders
    style A1 fill:#ffffff,stroke:#B9C8DF,color:#130C49
    style A2 fill:#ffffff,stroke:#B9C8DF,color:#130C49
    style A3 fill:#ffffff,stroke:#B9C8DF,color:#130C49
    style B1 fill:#ffffff,stroke:#B9C8DF,color:#130C49
    style B2 fill:#ffffff,stroke:#B9C8DF,color:#130C49
    style C1 fill:#ffffff,stroke:#B9C8DF,color:#130C49

    %% Style subgraphs with brand colors
    style sg1 fill:#ffffff,stroke:#61BD73,stroke-width:2px,color:#130C49
    style sg2 fill:#ffffff,stroke:#130C49,stroke-width:2px,color:#130C49
    style sg3 fill:#ffffff,stroke:#7AD6EB,stroke-width:2px,color:#130C49
```

Notes:

- The code examples here are self-contained. You can copy and paste them into your own environment to try them out.
:::

## Requirements

To use Weaviate Embeddings, you will need:

- A Weaviate Cloud free cluster
- A Weaviate client library that supports Weaviate Embeddings

:::code-group{sync="languages"}
```bash title="Python"
pip install -U "weaviate-client[agents]"
```

```bash title="JavaScript/TypeScript"
npm install weaviate-client weaviate-agents
```

```bash title="Go"
go get github.com/weaviate/weaviate-go-client/v5
```

```xml title="Java"
<dependency>
  <groupId>io.weaviate</groupId>
  <artifactId>client6</artifactId>
  <version>6.2.0</version> <!-- Check latest version: https://github.com/weaviate/java-client  -->
</dependency>
```

```xml title="C#"
<PackageReference Include="Weaviate.Client" Version="1.0.0" />
```
:::

The Go client does not support Weaviate Embeddings directly. Pass the `X-Weaviate-Api-Key` and `X-Weaviate-Cluster-Url` headers manually when you instantiate the client.

## Step 1: Set up Weaviate

### 1.1 Create a new cluster

To create a **free cluster** in Weaviate Cloud, follow **[these instructions](../manage-clusters/create.md)**.

:::callout{intent="tip" title="TIP: Use the latest Weaviate version!"}
When possible, try to use the latest Weaviate version.
New releases include cutting-edge features, performance enhancements, and critical security updates to keep your application safe and up-to-date.
:::

### 1.2 Install a client library

We recommend using a [client library](../client-libraries/index.md) to work with Weaviate. Follow the instructions below to install one of the official client libraries, available in [Python](../client-libraries/python.md), [JavaScript/TypeScript](../client-libraries/typescript.md), [Go](../client-libraries/go.md), and [Java](../client-libraries/java.md).

:::code-group{sync="languages"}
```bash title="Python"
pip install -U "weaviate-client[agents]"
```

```bash title="JavaScript/TypeScript"
npm install weaviate-client weaviate-agents
```

```bash title="Go"
go get github.com/weaviate/weaviate-go-client/v5
```

```xml title="Java"
<dependency>
  <groupId>io.weaviate</groupId>
  <artifactId>client6</artifactId>
  <version>6.2.0</version> <!-- Check latest version: https://github.com/weaviate/java-client  -->
</dependency>
```

```xml title="C#"
<PackageReference Include="Weaviate.Client" Version="1.0.0" />
```
:::

### 1.3 Connect to Weaviate Cloud

Weaviate Embeddings is integrated with Weaviate Cloud. Your Weaviate Cloud credentials will be used to authorize your Weaviate Cloud instance's access for Weaviate Embeddings.

:::code-group{sync="languages"}
```python title="Python"
import weaviate
from weaviate.classes.init import Auth
import os

# Best practice: store your credentials in environment variables
weaviate_url = os.getenv("WEAVIATE_URL")
weaviate_key = os.getenv("WEAVIATE_API_KEY")

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,                     # Weaviate URL: "REST Endpoint" in Weaviate Cloud console
    auth_credentials=Auth.api_key(weaviate_key),  # Weaviate API key: "ADMIN" API key in Weaviate Cloud console
)

print(client.is_ready())  # Should print: `True`

# Work with Weaviate

client.close()
```

```typescript title="JavaScript/TypeScript"
import weaviate from 'weaviate-client'

// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL as string;        // Weaviate URL: "REST Endpoint" in Weaviate Cloud console
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string; // Weaviate API key: "ADMIN" API key in Weaviate Cloud console

const client = await weaviate.connectToWeaviateCloud(
  weaviateUrl,  
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey),  
  }
)

// Work with Weaviate

client.close()
```

```goraw title="Go"
```
:::

## Step 2: Populate the database

### 2.1 Define a collection

Now we can define a collection that will store our data. When creating a collection, you need to specify one of the [available models](models.md) for the vectorizer to use. This model will be used to create vector embeddings from your data.

:::code-group{sync="languages"}
```python title="Python" {5-17}
from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "DemoCollection",
    properties=[
        Property(name="title", data_type=DataType.TEXT),
    ],
    vector_config=[
        Configure.Vectors.text2vec_weaviate(
            name="title_vector",
            source_properties=["title"],
            model="Snowflake/snowflake-arctic-embed-l-v2.0",
            # Further options
            # dimensions=256
            # base_url="<custom_weaviate_embeddings_url>",
        )
    ],
    # Additional parameters not shown
)
```

```typescript title="JavaScript/TypeScript" {9-19}
await client.collections.create({
  name: 'DemoCollection',
  properties: [
    {
      name: 'title',
      dataType: 'text' as const,
    },
  ],
  vectorizers: [
    weaviate.configure.vectors.text2VecWeaviate({
        name: 'title_vector',
        sourceProperties: ['title'],
        model: 'Snowflake/snowflake-arctic-embed-l-v2.0',
        // Further options
        // dimensions: 256,
        // baseURL: '<custom_weaviate_embeddings_url>',
      },
    ),
  ],
  // Additional parameters not shown
});
```

```goraw title="Go" {1-22}
// Define the collection
weaviateVectorizerArcticEmbedLV20 := &models.Class{
  Class: "DemoCollection",
  VectorConfig: map[string]models.VectorConfig{
    "title_vector": {
      VectorIndexType: `hnsw`,
      Vectorizer: map[string]interface{}{
        "text2vec-weaviate": map[string]interface{}{
          "model":      "Snowflake/snowflake-arctic-embed-l-v2.0",
          "dimensions": 1024, // Or 256
          // "base_url":   "<custom_weaviate_url>",
        },
      },
    },
  },
}

// add the collection
err = client.Schema().ClassCreator().WithClass(weaviateVectorizerArcticEmbedLV20).Do(ctx)
if err != nil {
  panic(err)
}
```
:::

For more information about the available model options visit the [Choose a model](models.md) page.

### 2.2 Import objects

After configuring the vectorizer, [import data](../how-to-manage-objects/import.md) into Weaviate. Weaviate generates embeddings for text objects using the specified model.

:::code-group{sync="languages"}
```python title="Python" {13-20}
source_objects = [
    {"title": "The Shawshank Redemption", "description": "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places."},
    {"title": "The Godfather", "description": "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga."},
    {"title": "The Dark Knight", "description": "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City."},
    {"title": "Jingle All the Way", "description": "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve."},
    {"title": "A Christmas Carol", "description": "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption."}
]

collection = client.collections.use("DemoCollection")

with collection.batch.fixed_size(batch_size=200) as batch:
    for src_obj in source_objects:
        # The model provider integration will automatically vectorize the object
        batch.add_object(
            properties={
                "title": src_obj["title"],
                "description": src_obj["description"],
            },
            # vector=vector  # Optionally provide a pre-obtained vector
        )
        if batch.number_errors > 10:
            print("Batch import stopped due to excessive errors.")
            break

failed_objects = collection.batch.failed_objects
if failed_objects:
    print(f"Number of failed imports: {len(failed_objects)}")
    print(f"First failed object: {failed_objects[0]}")
```

```typescript title="JavaScript/TypeScript"
let srcObjects = [
  { title: "The Shawshank Redemption", description: "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places." },
  { title: "The Godfather", description: "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga." },
  { title: "The Dark Knight", description: "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City." },
  { title: "Jingle All the Way", description: "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve." },
  { title: "A Christmas Carol", description: "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption." }
];
```

```goraw title="Go" {9-44}
var sourceObjects = []map[string]string{
  {"title": "The Shawshank Redemption", "description": "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places."},
  {"title": "The Godfather", "description": "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga."},
  {"title": "The Dark Knight", "description": "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City."},
  {"title": "Jingle All the Way", "description": "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve."},
  {"title": "A Christmas Carol", "description": "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption."},
}

// Convert items into a slice of models.Object
objects := []models.PropertySchema{}
for i := range sourceObjects {
  objects = append(objects, map[string]interface{}{
    // Populate the object with the data
    "title":       sourceObjects[i]["title"],
    "description": sourceObjects[i]["description"],
  })
}

// Batch write items
batcher := client.Batch().ObjectsBatcher()
for _, dataObj := range objects {
  batcher.WithObjects(&models.Object{
    Class:      "DemoCollection",
    Properties: dataObj,
  })
}

// Flush
batchRes, err := batcher.Do(ctx)

// Error handling
if err != nil {
  panic(err)
}
for _, res := range batchRes {
  if res.Result.Errors != nil {
    for _, err := range res.Result.Errors.Error {
      if err != nil {
        fmt.Printf("Error details: %v\n", *err)
        panic(err.Message)
      }
    }
  }
}
```
:::

## Step 3: Query your data

Once the vectorizer is configured, Weaviate will perform vector search operations using the specified model.

### Vector (near text) search

When you perform a [vector search](../how-to-query-search/similarity.md#search-with-text), Weaviate converts the text query into an embedding using the specified model and returns the most similar objects from the database.

The query below returns the `n` most similar objects from the database, set by `limit`.

:::code-group{sync="languages"}
```python title="Python" {3-6}
collection = client.collections.use("DemoCollection")

response = collection.query.near_text(
    query="A holiday film",  # The model provider integration will automatically vectorize the query
    limit=2
)

for obj in response.objects:
    print(obj.properties["title"])
```

```typescript title="JavaScript/TypeScript"
const collectionName = 'DemoCollection'
const myCollection = client.collections.use(collectionName)
```

```goraw title="Go" {1-9}
nearTextResponse, err := client.GraphQL().Get().
  WithClassName("DemoCollection").
  WithFields(
    graphql.Field{Name: "title"},
  ).
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"A holiday film"})).
  WithLimit(2).
  Do(ctx)

if err != nil {
  panic(err)
}
fmt.Printf("%v", nearTextResponse)
```
:::

## Next steps

::::card-grid
:::card{title="Choose a model" href="/guides/cloud-weaviate-embeddings-models" icon="clipboard-list"}
Check out which additional models are available through Weaviate Embeddings.
:::

:::card{title="Explore hybrid search" href="/guides/how-to-query-search-hybrid" icon="search"}
Discover how hybrid search combines keyword matching and semantic search.
:::
::::

## Support

If you use **Weaviate Cloud** (Database cluster(s) or Weaviate product in the cloud) or have a self-hosted support package, open a ticket in the [Support Portal](https://support.weaviate.io) or email [Weaviate support](mailto\:support@weaviate.io) directly. To add a [support plan](https://weaviate.io/support-plans), contact [Weaviate sales](https://weaviate.io/pricing#contact-sales).

Use the **Support Portal** for direct help from the Weaviate team: open and track tickets, and we'll respond in line with your support plan. The **Community Forum** is open to everyone, and a great place to ask questions, get help with your cluster, and connect with other developers. For all the ways to get help, see the [Support overview](../support/overview.md).

::::card-grid
:::card{title="Weaviate Support Portal" href="https://support.weaviate.io" icon="headset"}
Direct help from the Weaviate team for Weaviate Cloud. Open and track tickets in the **Support Portal**.
:::

:::card{title="Weaviate Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions, share ideas, and connect with other developers on our **Community forum**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.