Local instances

Follow these steps to connect to a locally hosted Weaviate instance.

Local connection URL

Docker instances default to http://localhost:8080. The gRPC port, 50051, is also on localhost.

If your instance runs on Kubernetes, see the host and port values in your Helm chart's values.yaml file.

No authentication enabled

To connect to a local instance without authentication, follow these examples.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)Shell

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate

client = weaviate.connect_to_local()

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';


const client = await weaviate.connectToLocal()

console.log(client)

package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
)

// Create the client
func CreateClient() {
cfg := weaviate.Config{
Host:       "localhost:8080",
Scheme:     "http",
        Headers:    nil,
}

client, err := weaviate.NewClient(cfg)
if err != nil {
fmt.Println(err)
}

// Check the connection
live, err := client.Misc().LiveChecker().Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", live)

}

func main() {
CreateClient()
}

WeaviateClient client = WeaviateClient.connectToLocal();

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

package your.application;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;

public class App
{
public static void main( String[] args ) throws Exception
{

String scheme = "http";
String host = "localhost:8080";

Config config = new Config(scheme, host);
WeaviateClient client = new WeaviateClient(config);
}
}

WeaviateClient client = Connect.Local();

var isReady = await client.IsReady();
Console.WriteLine(isReady);

curl http://localhost:8080/v1/meta | jq

Change the URL or port

To change the default URL or port number, follow these examples.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)Shell

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate

client = weaviate.connect_to_local(
    host="127.0.0.1",  # Use a string to specify the host
    port=8080,
    grpc_port=50051,
)

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';


const client = await weaviate.connectToLocal(
 {
    host: "127.0.0.1",   // URL only, no http prefix
    port: 8080,
    grpcPort: 50051,     // Default is 50051, WCD uses 443
 })

async function main() {
  console.log(await client.isReady())
  await client.close()
}

main()

package main

import (
"context"
"fmt"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
)

// Create the client
func CreateClient() {
cfg := weaviate.Config{
Host:       "localhost:8080",
Scheme:     "http",
        Headers:    nil,
        // The Go client doesn't use the gRPC port
}

client, err := weaviate.NewClient(cfg)
if err != nil {
fmt.Println(err)
}

// Check the connection
live, err := client.Misc().LiveChecker().Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", live)

}

func main() {
CreateClient()
}

WeaviateClient client = WeaviateClient
    .connectToLocal(config -> config.host("127.0.0.1").port(8080));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

package your.application;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;

public class App
{
public static void main( String[] args ) throws Exception
{

String scheme = "http";
String host = "localhost:8080";
// The Java client doesn't use the gRPC port

Config config = new Config(scheme, host);
WeaviateClient client = new WeaviateClient(config);
}
}

var config = new ClientConfiguration
{
    RestAddress = "127.0.0.1",
    RestPort = 8080,
    GrpcAddress = "127.0.0.1",
    GrpcPort = 50051 // Default gRPC port
};
WeaviateClient client = new WeaviateClient(config);

var isReady = await client.IsReady();
Console.WriteLine(isReady);

curl http://localhost:8080/v1/meta | jq
# The cURL connection doesn't use the gRPC port

Authentication enabled

To authenticate with a Weaviate API key, follow these examples.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)Shell

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate
from weaviate.classes.init import Auth

# Best practice: store your credentials in environment variables
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_local(
    auth_credentials=Auth.api_key(weaviate_api_key)
)

print(client.is_ready())

assert client.is_ready()

import weaviate, { WeaviateClient } from 'weaviate-client';

// Set this environment variable
// WEAVIATE_LOCAL_API_KEY   your Weaviate instance API key

const weaviateKey = process.env.WEAVIATE_LOCAL_API_KEY as string

const client = await weaviate.connectToLocal(
   { 
    port:8099,
    grpcPort:50052, 
    authCredentials: new weaviate.ApiKey(weaviateKey)
  }
)

console.log(client)

// Set this environment variable
// WEAVIATE_API_KEY  your Weaviate instance API key

package main

import (
"context"
"fmt"
"os"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
)

// Create the client
func CreateClient() {
cfg := weaviate.Config{
Host:       "localhost:8080",
Scheme:     "http",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
        Headers:    nil,
}

client, err := weaviate.NewClient(cfg)
if err != nil {
fmt.Println(err)
}

// Check the connection
live, err := client.Misc().LiveChecker().Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", live)

}

func main() {
CreateClient()
}

// Best practice: store your credentials in environment variables
final String weaviateApiKey = System.getenv("WEAVIATE_LOCAL_API_KEY");

// The local() factory doesn't support auth, so we must use custom().
WeaviateClient client = WeaviateClient.connectToCustom(
    config -> config.authentication(Authentication.apiKey(weaviateApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

// Set this environment variable
// WEAVIATE_API_KEY  your Weaviate instance API key

package your.application;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.WeaviateAuthClient;

public class App
{
public static void main( String[] args ) throws Exception
{

String scheme = "http";
String host = "localhost:8080";
String apiKey = System.getenv("WEAVIATE_API_KEY");

Config config = new Config(scheme, host);
WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);
}
}

// Best practice: store your credentials in environment variables
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_LOCAL_API_KEY");

// The Connect.Local() helper doesn't support auth, so we must use a custom configuration.
var config = new ClientConfiguration
{
    Credentials = Auth.ApiKey(weaviateApiKey)
};
WeaviateClient client = new WeaviateClient(config);

var isReady = await client.IsReady();
Console.WriteLine(isReady);

# Set this environment variable
# WEAVIATE_API_KEY  your Weaviate instance API key

curl http://localhost:8080/v1/meta -H "Authorization: Bearer ${WEAVIATE_API_KEY}" | jq

OIDC authentication

For details on authentication with OpenID Connect (OIDC), see OIDC configuration.

For additional client examples, see OIDC authentication.

Third party API keys

Integrations that use external APIs often need API keys. To add third party API keys, follow these examples:

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)Shell

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import os
import weaviate

# Best practice: store your credentials in environment variables
cohere_api_key = os.environ["COHERE_API_KEY"]

client = weaviate.connect_to_local(
    headers={
        "X-Cohere-Api-Key": cohere_api_key
    }
)

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';

// Set this environment variable
// COHERE_API_KEY    your Cohere API key

const cohereKey = process.env.COHERE_API_KEY as string

const client = await weaviate.connectToLocal(
  {
    headers: {
     'X-Cohere-Api-Key':  cohereKey,
    }
  }
)

console.log(client)

// Set this environment variable
// COHERE_API_KEY    your Cohere API key

package main

import (
"context"
"fmt"
"os"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
)

// Create the client
func CreateClient() {
cfg := weaviate.Config{
Host:       "localhost:8080",
Scheme:     "http",
        Headers:     map[string]string{
            "X-Cohere-Api-Key": os.Getenv("WEAVIATE_COHERE_KEY"),
        },
}

client, err := weaviate.NewClient(cfg)
if err != nil {
fmt.Println(err)
}

// Check the connection
live, err := client.Misc().LiveChecker().Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", live)

}

func main() {
CreateClient()
}

// Best practice: store your credentials in environment variables
final String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client = WeaviateClient.connectToLocal(
    config -> config.setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

// Set this environment variable
// COHERE_API_KEY    your Cohere API key

package your.application;

import java.util.HashMap;
import java.util.Map;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;

public class App
{
public static void main( String[] args ) throws Exception
{

String scheme = "http";
String host = "localhost:8080";
String cohereKey = System.getenv("COHERE_API_KEY");

Map<String, String> headers = new HashMap<String, String>() { {
    put("X-Cohere-Api-Key", cohereKey);
} };

Config config = new Config(scheme, host, headers);
WeaviateClient client = new WeaviateClient(config);
}
}

// Best practice: store your credentials in environment variables
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

var config = new ClientConfiguration
{
    Headers = new Dictionary<string, string>
    {
        { "X-Cohere-Api-Key", cohereApiKey }
    }
};
WeaviateClient client = new WeaviateClient(config);

var isReady = await client.IsReady();
Console.WriteLine(isReady);

# Set this environment variable
# COHERE_API_KEY    your Cohere API key

curl http://localhost:8080/v1/meta \
-H 'Content-Type: application/json' \
-H "X-Cohere-Api-Key: ${COHERE_API_KEY}" | jq

Environment variables

warning

Do not hard-code API keys or other credentials in your client code. Use environment variables or a similar secure coding technique instead.

Environment variables keep sensitive details out of your source code. Your application imports the information to runtime.

Set an environment variable.

In these examples, the environment variable names are in UPPER_CASE.

BashWindows PowerShellWindows Command Prompt

export WEAVIATE_URL="http://localhost:8080"
export WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"

$Env:WEAVIATE_URL="http://localhost:8080"
$Env:WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"

set WEAVIATE_URL=http://localhost:8080
set WEAVIATE_API_KEY=sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz

Import an environment variable.

PythonJavaScript/TypeScriptGoJava

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

weaviate_url = os.getenv("WEAVIATE_URL")
weaviate_key = os.getenv("WEAVIATE_API_KEY")

const weaviateUrl = process.env.WEAVIATE_URL;
const weaviateKey = process.env.WEAVIATE_API_KEY;

weaviateUrl := os.Getenv("WEAVIATE_URL")
weaviateKey := os.Getenv("WEAVIATE_API_KEY")

String weaviateUrl = System.getenv("WEAVIATE_URL");
String weaviateKey = System.getenv("WEAVIATE_API_KEY");

gRPC timeouts

The Python client v4 and TypeScript client v3 use gRPC. The gRPC protocol is sensitive to network delay. If you encounter connection timeouts, adjust the timeout values for initialization, queries, and insertions.

PythonJavaScript/TypeScriptJava v6 (Beta)C# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate
from weaviate.classes.init import AdditionalConfig, Timeout

client = weaviate.connect_to_local(
    port=8080,
    grpc_port=50051,
    additional_config=AdditionalConfig(
        timeout=Timeout(init=30, query=60, insert=120)  # Values in seconds
    )
)

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';


const client = await weaviate.connectToLocal(
   {  timeout: { init: 30, query: 60, insert: 120 }, } // Values in seconds
)

console.log(client)

  // Coming soon

    // Coming soon

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.