REST - /v1/backups

Introduction

See the Backups page for a general introduction, configuration, and tech background of Backups.

API

Create Backup

Once the modules are enabled and the configuration is provided, you can start a backup on any running instance with a single HTTP request.

Method and URL

POST /v1/backups/{backend}

Parameters

URL Parameters

name	type	required	description
`backend`	string	yes	The name of the backup provider module without the `backup-` prefix, for example `s3`, `gcp`, or `filesystem`.

Request Body

The request takes a json object with the following properties:

name	type	required	description
`id`	string (lowercase letters, numbers, underscore, minus)	yes	The id of the backup. This string must be provided on all future requests, such as status checking or restoration.
`include`	list of strings	no	An optional list of class names to be included in the backup. If not set, all classes are included.
`exclude`	list of strings	no	An optional list of class names to be excluded from the backup. If not set, no classes are excluded.

Note: You cannot set include and exclude at the same time. Set none or exactly one of those.

Python
JavaScript
Go
Java
Curl

import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.backup.create(
  backup_id="my-very-first-backup",
  backend="filesystem",
  include_classes=["Article", "Publication"],
  wait_for_completion=True,
)

print(result)

const weaviate = require('weaviate-client');

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

client.backup.creator()
  .withIncludeClassNames('Article', 'Publication')
  .withBackend('filesystem')
  .withBackupId('my-very-first-backup')
  .withWaitForCompletion(true)
  .do()
  .then(console.log)
  .catch(console.error)

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/backup"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  result, err := client.Backup().Creator().
    WithIncludeClassNames("Article", "Publication").
    WithBackend(backup.BACKEND_FILESYSTEM).
    WithBackupID("my-very-first-backup").
    WithWaitForCompletion(true).
    Do(context.Background())

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

package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.backup.model.Backend;
import technology.semi.weaviate.client.v1.backup.model.BackupCreateResponse;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<BackupCreateResponse> result = client.backup().creator()
      .withIncludeClassNames("Article", "Publication")
      .withBackend(Backend.FILESYSTEM)
      .withBackupId("my-very-first-backup")
      .withWaitForCompletion(true)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

$ curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
         "id": "my-very-first-backup",
         "include": ["Article", "Publication"]
        }' \
    http://localhost:8080/v1/backups/filesystem

While you are waiting for a backup to complete, Weaviate stays fully usable.

Asynchronous Status Checking

All client implentations have a "wait for completion" option which will poll the backup status in the background and only return once the backup has completed (successfully or unsuccessfully).

If you set the "wait for completion" option to false, you can also check the status yourself using the Backup Creation Status API.

GET /v1/backups/{backend}/{backup_id}

Parameters

URL Parameters

name	type	required	description
`backend`	string	yes	The name of the backup provider module without the `backup-` prefix, for example `s3`, `gcp`, or `filesystem`.
`backup_id`	string	yes	The user-provided backup identifier that was used when sending the request to create the backup.

The response contains a "status" field. If the status is SUCCESS, the backup is complete. If the status is FAILED, an additional error is provided.

Python
JavaScript
Go
Java
Curl

import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.backup.get_create_status(
  backup_id="my-very-first-backup",
  backend="filesystem",
)

print(result)

const weaviate = require('weaviate-client');

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

client.backup.createStatusGetter()
  .withBackend('filesystem')
  .withBackupId('my-very-first-backup')
  .do()
  .then(console.log)
  .catch(console.error)

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/backup"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  result, err := client.Backup().CreateStatusGetter().
    WithBackend(backup.BACKEND_FILESYSTEM).
    WithBackupID("my-very-first-backup").
    Do(context.Background())

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

package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.backup.model.Backend;
import technology.semi.weaviate.client.v1.backup.model.BackupCreateStatusResponse;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<BackupCreateStatusResponse> result = client.backup().createStatusGetter()
      .withBackend(Backend.FILESYSTEM)
      .withBackupId("my-very-first-backup")
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

$ curl http://localhost:8080/v1/backups/filesystem/my-very-first-backup

Restore Backup

You can restore any backup to any machine as long as the number of nodes between source and target are identical. The backup does not need to be created on the same instance. Once a backup backend is configured, you can restore a backup with a single HTTP request.

Note that a restore fails if any of the classes already exist on this instance.

Method and URL

POST /v1/backups/{backend}/{backup_id}/restore

Parameters

URL Parameters

name	type	required	description
`backend`	string	yes	The name of the backup provider module without the `backup-` prefix, for example `s3`, `gcp`, or `filesystem`.
`backup_id`	string	yes	The user-provided backup identifier that was used when sending the request to create the backup.

Request Body

The request takes a json object with the following properties:

name	type	required	description
`include`	list of strings	no	An optional list of class names to be included in the backup. If not set, all classes are included.
`exclude`	list of strings	no	An optional list of class names to be excluded from the backup. If not set, no classes are excluded.

Note 1: You cannot set include and exclude at the same time. Set none or exactly one of those.

Note 2: include and exclude is relative to the classes contained in the backup. The restore process does not know which classes existed on the source machine if they were not part of the backup.

Python
JavaScript
Go
Java
Curl

import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.backup.restore(
  backup_id="my-very-first-backup",
  backend="filesystem",
  exclude_classes="Article",
  wait_for_completion=True,
)

print(result)

const weaviate = require('weaviate-client');

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

client.backup.restorer()
  .withExcludeClassNames('Article')
  .withBackend('filesystem')
  .withBackupId('my-very-first-backup')
  .withWaitForCompletion(true)
  .do()
  .then(console.log)
  .catch(console.error)

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/backup"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  result, err := client.Backup().Restorer().
    WithExcludeClassNames("Article").
    WithBackend(backup.BACKEND_FILESYSTEM).
    WithBackupID("my-very-first-backup").
    WithWaitForCompletion(true).
    Do(context.Background())

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

package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.backup.model.Backend;
import technology.semi.weaviate.client.v1.backup.model.BackupRestoreResponse;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<BackupRestoreResponse> result = client.backup().restorer()
      .withExcludeClassNames("Article")
      .withBackend(Backend.FILESYSTEM)
      .withBackupId("my-very-first-backup")
      .withWaitForCompletion(true)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

$ curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
         "id": "my-very-first-backup",
         "exclude": ["Article"]
        }' \
    http://localhost:8080/v1/backups/filesystem/my-very-first-backup/restore

Asynchronous Status Checking

All client implentations have a "wait for completion" option which will poll the backup status in the background and only return once the backup has completed (successfully or unsuccessfully).

If you set the "wait for completion" option to false, you can also check the status yourself using the Backup Restore Status API.

GET /v1/backups/{backend}/{backup_id}/restore

Parameters

URL Parameters

name	type	required	description
`backend`	string	yes	The name of the backup provider module without the `backup-` prefix, for example `s3`, `gcp`, or `filesystem`.
`backup_id`	string	yes	The user-provided backup identifier that was used when sending the requests to create and restore the backup.

The response contains a "status" field. If the status is SUCCESS, the restore is complete. If the status is FAILED, an additional error is provided.

Python
JavaScript
Go
Java
Curl

import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.backup.get_restore_status(
  backup_id="my-very-first-backup",
  backend="filesystem",
)

print(result)

const weaviate = require('weaviate-client');

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

client.backup.restoreStatusGetter()
  .withBackend('filesystem')
  .withBackupId('my-very-first-backup')
  .do()
  .then(console.log)
  .catch(console.error)

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/backup"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  result, err := client.Backup().RestoreStatusGetter().
    WithBackend(backup.BACKEND_FILESYSTEM).
    WithBackupID("my-very-first-backup").
    Do(context.Background())

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

package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.backup.model.Backend;
import technology.semi.weaviate.client.v1.backup.model.BackupRestoreStatusResponse;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<BackupRestoreStatusResponse> result = client.backup().restoreStatusGetter()
      .withBackend(Backend.FILESYSTEM)
      .withBackupId("my-very-first-backup")
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

$ curl http://localhost:8080/v1/backups/filesystem/my-very-first-backup/restore

Learn more about Backups

Discover more about Backups Configuration, inlcuding Backups to S3 or GCS, Technical Considerations of Backups, as well as additional use cases.

Introduction​

API​

Create Backup​

Method and URL​

Parameters​

URL Parameters​

Request Body​

Asynchronous Status Checking​

Parameters​

URL Parameters​

Restore Backup​

Method and URL​

Parameters​

URL Parameters​

Request Body​

Asynchronous Status Checking​

Parameters​

URL Parameters​

Learn more about Backups

Introduction

API

Create Backup

Method and URL

Parameters

URL Parameters

Request Body

Asynchronous Status Checking

Parameters

URL Parameters

Restore Backup

Method and URL

Parameters

URL Parameters

Request Body

Asynchronous Status Checking

Parameters

URL Parameters