> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Namespaces

Upstash Vector allows you to partition a single index into multiple isolated namespaces. Each namespace acts as a self-contained subset of the index, and read and write requests are limited to one namespace.

Each vector index has at least one default namespace and optionally many more.

If no namespace is specified, the operations will use the default namespace, which has the name `""` (empty string).

<Note>
  Indexes created before the namespaces feature can still be used as they are,
  without modification. All operations are assumed to use the default namespace.
</Note>

## Using a Namespace

Namespaces are created implicitly when an upsert operation is performed, so there is no specific endpoint for creating a namespace.

For example, the code snippet below will create the namespace `ns` if it does not already exist, upsert and query the vector only on that namespace.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from upstash_vector import Index

    index = Index(
        url="UPSTASH_VECTOR_REST_URL",
        token="UPSTASH_VECTOR_REST_TOKEN",
    )

    index.upsert(
        [("id-0", [0.9215, 0.3897])],
        namespace="ns",
    )

    index.query(
        [0.9215, 0.3897],
        top_k=5,
        namespace="ns",
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={"system"}
    import { Index } from "@upstash/vector"

    const index = new Index({
      url: "UPSTASH_VECTOR_REST_URL",
      token: "UPSTASH_VECTOR_REST_TOKEN",
    })

    const namespace = index.namespace("ns")

    await namespace.upsert({
      id: "id-0",
      vector: [0.9215, 0.3897],
    })

    await namespace.query({
      vector: [0.9215, 0.3897],
      topK: 5,
    })
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={"system"}
    package main

    import (
    	"github.com/upstash/vector-go"
    )

    func main() {
    	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

    	namespace := index.Namespace("ns")

    	namespace.Upsert(vector.Upsert{
    		Id:     "id-0",
    		Vector: []float32{0.9215, 0.3897},
    	})

    	namespace.Query(vector.Query{
    		Vector: []float32{0.9215, 0.3897},
    		TopK:   5,
    	})
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={"system"}
    use Upstash\Vector\Index;
    use Upstash\Vector\VectorUpsert;
    use Upstash\Vector\VectorQuery;

    $index = new Index(
      url: 'UPSTASH_VECTOR_REST_URL',
      token: 'UPSTASH_VECTOR_REST_TOKEN',
    );

    $namespace = $index->namespace('ns');

    $namespace->upsert(new VectorUpsert(
      id: 'id-0',
      vector: [0.9215, 0.3897],
    ));

    $namespace->query(new VectorQuery(
      vector: [0.9215, 0.3897],
      topK: 5,
    ));
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={"system"}
    curl $UPSTASH_VECTOR_REST_URL/upsert/ns \
      -X POST \
      -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
      -d '{"id":"id-0", "vector":[0.9215,0.3897]}'

    curl $UPSTASH_VECTOR_REST_URL/query/ns \
      -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
      -d '{"vector":[0.9215,0.3897], "topK" : 5}'
    ```
  </Tab>
</Tabs>

Under the hood, when using a namespace, your requests are sent to `<vector-url>/<command>/namespace-name` to only be executed only against that namespace.

## Deleting a Namespace

Namespaces can be deleted by using the
[Delete Namespace](../api/endpoints/delete-namespace) API.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from upstash_vector import Index

    index = Index(
        url="UPSTASH_VECTOR_REST_URL",
        token="UPSTASH_VECTOR_REST_TOKEN",
    )

    index.delete_namespace("ns")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={"system"}
    import { Index } from "@upstash/vector"

    const index = new Index({
      url: "UPSTASH_VECTOR_REST_URL",
      token: "UPSTASH_VECTOR_REST_TOKEN",
    })

    await index.deleteNamespace("ns")
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={"system"}
    package main

    import (
    	"github.com/upstash/vector-go"
    )

    func main() {
    	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

    	namespace := index.Namespace("ns")

    	namespace.DeleteNamespace()
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={"system"}
    use Upstash\Vector\Index;

    $index = new Index(
      url: 'UPSTASH_VECTOR_REST_URL',
      token: 'UPSTASH_VECTOR_REST_TOKEN',
    );

    $index->namespace('ns')->deleteNamespace();
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={"system"}
    curl $UPSTASH_VECTOR_REST_URL/delete-namespace/ns \
      -X DELETE \
      -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
    ```
  </Tab>
</Tabs>

## Listing Namespaces

All active namespaces can be listed by using the
[List Namespaces](../api/endpoints/list-namespaces) API.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from upstash_vector import Index

    index = Index(
        url="UPSTASH_VECTOR_REST_URL",
        token="UPSTASH_VECTOR_REST_TOKEN",
    )

    index.list_namespaces()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={"system"}
    import { Index } from "@upstash/vector"

    const index = new Index({
      url: "UPSTASH_VECTOR_REST_URL",
      token: "UPSTASH_VECTOR_REST_TOKEN",
    })

    await index.listNamespaces()
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={"system"}
    package main

    import (
    	"github.com/upstash/vector-go"
    )

    func main() {
    	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

    	index.ListNamespaces()
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={"system"}
    use Upstash\Vector\Index;

    $index = new Index(
      url: 'UPSTASH_VECTOR_REST_URL',
      token: 'UPSTASH_VECTOR_REST_TOKEN',
    );

    $index->listNamespaces();
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={"system"}
    curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
      -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
    ```
  </Tab>
</Tabs>