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.

Python Client v4

import weaviate

client = weaviate.connect_to_local()

print(client.is_ready())

  API docs

Python Client v3

import weaviate

# Create the client
client = weaviate.Client(
    url="http://localhost:8080"
)

print(client.is_ready())

  API docs  Deprecated (v3)

JS/TS Client v3

import weaviate from 'weaviate-client'

const client = await weaviate.connectToLocal()

console.log(client)

  API docs

JS/TS Client v2

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

const client: WeaviateClient = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

console.log(client)

Go

package main

import (
	"context"
	"fmt"

	"github.com/weaviate/weaviate-go-client/v4/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()
}

  API docs

Java

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);
}
}

  API docs

cURL

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

Change the URL or port

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

Python Client v4

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())

  API docs

Python Client v3

import weaviate

# Create the client
client = weaviate.Client(
    url="http://127.0.0.1:8080"
    # The v3 client doesn't use the gRPC port
)

print(client.is_ready())

  API docs  Deprecated (v3)

JS/TS Client v3

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())
}

main()

  API docs

JS/TS Client v2

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

const client = weaviate.client({
  scheme: 'http',
  host: '127.0.0.1:8080',
  // The v2 client doesn't use the gRPC port
});

console.log(client)

Go

package main

import (
	"context"
	"fmt"

	"github.com/weaviate/weaviate-go-client/v4/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()
}

  API docs

Java

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);
}
}

  API docs

cURL

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.

Python Client v4

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()

  API docs

Python Client v3

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

import os
import weaviate

# Create the client
client = weaviate.Client(
    url="http://localhost:8080",
    auth_client_secret=weaviate.auth.AuthApiKey(api_key=os.getenv("WEAVIATE_API_KEY")),
)

print(client.is_ready())

  API docs  Deprecated (v3)

JS/TS Client v3

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

import weaviate from 'weaviate-client'

const weaviateKey = process.env.WEAVIATE_ADMIN_KEY as string

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

console.log(client)

  API docs

JS/TS Client v2

import weaviate, { ApiKey } from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
  apiKey: new ApiKey(process.env.WEAVIATE_API_KEY),
});

console.log(client)

Go

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

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/weaviate/weaviate-go-client/v4/weaviate"
    "github.com/weaviate/weaviate-go-client/v4/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()
}

  API docs

Java

// 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);
}
}

  API docs

cURL

# 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:

Python Client v4

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())

  API docs

Python Client v3

# Set this environment variable
# COHERE_API_KEY     your Cohere API key

import os
import weaviate

client = weaviate.Client(
    url="http://localhost:8080",
    additional_headers={
        "X-Cohere-Api-Key": os.getenv("COHERE_API_KEY")
    }
)

print(client.is_ready())

  API docs  Deprecated (v3)

JS/TS Client v3

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

import weaviate from 'weaviate-client'

const cohereKey = process.env.COHERE_API_KEY as string

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

console.log(client)

  API docs

JS/TS Client v2

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

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

const client: WeaviateClient = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
  headers: {
   'X-Cohere-Api-Key': process.env.COHERE_API_KEY,
 },
});

console.log(client)

Go

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

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/weaviate/weaviate-go-client/v4/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()
}

  API docs

Java

// 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);
}
}

  API docs

cURL

# 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

danger

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.

Bash/Zsh

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

Windows PowerShell

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

Windows Command Prompt

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

Import an environment variable.

Python

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

JS/TS

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

Go

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

Java

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.

Python Client v4

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())

  API docs

JS/TS Client v3

import weaviate from 'weaviate-client'

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

console.log(client)

  API docs

Questions and feedback

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

• Technical questions
• Documentation feedback