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 , gcs , azure , 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, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
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 io.weaviate;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.backup.model.Backend;
import io.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 implementations 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 , gcs , azure , 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, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
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 io.weaviate;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.backup.model.Backend;
import io.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.
There are two important conditions to note, which can cause a restore to fail:
- If any of the classes already exist on the target restoration node(s).
- If the node names of the backed-up class' node(s) do not match those of the target restoration node(s).
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 , gcs , azure , 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, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
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 io.weaviate;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.backup.model.Backend;
import io.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 implementations 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 , gcs , azure , 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, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
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 io.weaviate;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.backup.model.Backend;
import io.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, including Backups to S3, GCS, or Azure, Technical Considerations of Backups, as well as additional use cases.