快照

自 v0.8.4 版本起可用

快照是tar归档文件，包含特定时间特定节点上特定集合的数据和配置。在分布式设置中，当集群中有多个节点时，处理单个集合时必须分别为每个节点创建快照。

此功能可用于存档数据或轻松复制现有部署。对于灾难恢复，Qdrant Cloud 用户可能更倾向于使用备份，这是数据的物理磁盘级副本。

有关如何使用快照的逐步指南，请参阅我们的教程。

创建快照

为现有集合创建新快照：

POST /collections/{collection_name}/snapshots

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

client.create_snapshot(collection_name="{collection_name}")

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.createSnapshot("{collection_name}");

use qdrant_client::Qdrant;

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.create_snapshot("{collection_name}").await?;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;

QdrantClient client =
      new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client.createSnapshotAsync("{collection_name}").get();

using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.CreateSnapshotAsync("{collection_name}");

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
	Host: "localhost",
	Port: 6334,
})

client.CreateSnapshot(context.Background(), "{collection_name}")

这是一个同步操作，将会在snapshot_path中生成一个tar归档文件。

删除快照

自 v1.0.0 起可用

DELETE /collections/{collection_name}/snapshots/{snapshot_name}

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

client.delete_snapshot(
    collection_name="{collection_name}", snapshot_name="{snapshot_name}"
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.deleteSnapshot("{collection_name}", "{snapshot_name}");

use qdrant_client::qdrant::DeleteSnapshotRequestBuilder;
use qdrant_client::Qdrant;

let client = Qdrant::from_url("http://localhost:6334").build()?;

client
    .delete_snapshot(DeleteSnapshotRequestBuilder::new(
        "{collection_name}",
        "{snapshot_name}",
    ))
    .await?;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;

QdrantClient client =
    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client.deleteSnapshotAsync("{collection_name}", "{snapshot_name}").get();

using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.DeleteSnapshotAsync(collectionName: "{collection_name}", snapshotName: "{snapshot_name}");

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
	Host: "localhost",
	Port: 6334,
})

client.DeleteSnapshot(context.Background(), "{collection_name}", "{snapshot_name}")

列出快照

集合的快照列表：

GET /collections/{collection_name}/snapshots

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

client.list_snapshots(collection_name="{collection_name}")

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.listSnapshots("{collection_name}");

use qdrant_client::Qdrant;

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.list_snapshots("{collection_name}").await?;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;

QdrantClient client =
    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client.listSnapshotAsync("{collection_name}").get();

using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.ListSnapshotsAsync("{collection_name}");

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
	Host: "localhost",
	Port: 6334,
})

client.ListSnapshots(context.Background(), "{collection_name}")

检索快照

从集合中下载指定的快照作为文件：

GET /collections/{collection_name}/snapshots/{snapshot_name}

curl 'http://{qdrant-url}:6333/collections/{collection_name}/snapshots/snapshot-2022-10-10.snapshot' \
    -H 'api-key: ********' \
    --output 'filename.snapshot'

恢复快照

快照可以通过三种可能的方式恢复：

从URL或本地文件恢复 (useful for restoring a snapshot file that is on a remote server or already stored on the node)
从上传的文件恢复 (useful for migrating data to a new cluster)
启动期间恢复 (useful when running a self-hosted single-node Qdrant instance)

无论使用哪种方法，Qdrant 都会从快照中提取分片数据，并在集群中正确注册分片。如果集群中恢复的分片有其他活跃的副本，Qdrant 默认会将它们复制到新恢复的节点上，以保持数据一致性。

从URL或本地文件恢复

自 v0.11.3 版本起可用

这种恢复方法要求快照文件可以从URL下载或作为节点上的本地文件存在（例如，如果您之前在此节点上创建了快照）。如果您需要上传快照文件，请参阅下一节。

要从URL或本地文件恢复，请使用快照恢复端点。此端点接受像https://example.com这样的URL或像file:///tmp/snapshot-2022-10-10.snapshot这样的文件 URI。如果目标集合不存在，它将被创建。

PUT /collections/{collection_name}/snapshots/recover
{
  "location": "http://qdrant-node-1:6333/collections/{collection_name}/snapshots/snapshot-2022-10-10.shapshot"
}

from qdrant_client import QdrantClient

client = QdrantClient(url="http://qdrant-node-2:6333")

client.recover_snapshot(
    "{collection_name}",
    "http://qdrant-node-1:6333/collections/collection_name/snapshots/snapshot-2022-10-10.shapshot",
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.recoverSnapshot("{collection_name}", {
  location: "http://qdrant-node-1:6333/collections/{collection_name}/snapshots/snapshot-2022-10-10.shapshot",
});

从上传的文件中恢复

快照文件也可以作为文件上传，并使用从上传的快照恢复进行恢复。此端点接受请求体中的原始快照数据。如果目标集合不存在，将会创建它。

curl -X POST 'http://{qdrant-url}:6333/collections/{collection_name}/snapshots/upload?priority=snapshot' \
    -H 'api-key: ********' \
    -H 'Content-Type:multipart/form-data' \
    -F 'snapshot=@/path/to/snapshot-2022-10-10.shapshot'

此方法通常用于将数据从一个集群迁移到另一个集群，因此我们建议在该使用场景中将优先级设置为“snapshot”。

启动期间恢复

如果您有一个单节点部署，您可以在启动时恢复任何集合，它将立即可用。恢复快照是通过Qdrant CLI在启动时通过--snapshot参数完成的，该参数接受一对列表，例如:

例如：

./qdrant --snapshot /snapshots/test-collection-archive.snapshot:test-collection --snapshot /snapshots/test-collection-archive.snapshot:test-copy-collection

目标集合必须不存在，否则程序将退出并报错。

如果您希望覆盖现有集合，请谨慎使用--force_snapshot标志。

快照优先级

当将快照恢复到非空节点时，快照数据与现有数据之间可能会发生冲突。“priority”设置控制Qdrant如何处理这些冲突。优先级设置很重要，因为不同的优先级可能会产生非常不同的最终结果。默认优先级可能并不适用于所有情况。

可用的快照恢复优先级有：

replica: (默认) 优先使用现有数据而不是快照。
snapshot: 优先使用快照数据而非现有数据。
no_sync: 恢复快照时不进行任何额外的同步。

要从快照恢复一个新集合，您需要将优先级设置为snapshot。使用snapshot优先级时，快照中的所有数据将被恢复到集群上。使用replica优先级（默认）时，您最终会得到一个空集合，因为集群上的集合不包含任何点，并且该源被优先考虑。

no_sync 用于特殊用例，并不常用。它允许手动管理分片并在集群之间传输分片，而无需任何额外的同步。错误使用它会使您的集群处于损坏状态。

要从URL恢复，您需要在请求体中指定一个额外的参数：

PUT /collections/{collection_name}/snapshots/recover
{
  "location": "http://qdrant-node-1:6333/collections/{collection_name}/snapshots/snapshot-2022-10-10.shapshot",
  "priority": "snapshot"
}

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://qdrant-node-2:6333")

client.recover_snapshot(
    "{collection_name}",
    "http://qdrant-node-1:6333/collections/{collection_name}/snapshots/snapshot-2022-10-10.shapshot",
    priority=models.SnapshotPriority.SNAPSHOT,
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.recoverSnapshot("{collection_name}", {
  location: "http://qdrant-node-1:6333/collections/{collection_name}/snapshots/snapshot-2022-10-10.shapshot",
  priority: "snapshot"
});

curl -X POST 'http://qdrant-node-1:6333/collections/{collection_name}/snapshots/upload?priority=snapshot' \
    -H 'api-key: ********' \
    -H 'Content-Type:multipart/form-data' \
    -F 'snapshot=@/path/to/snapshot-2022-10-10.shapshot'

整个存储的快照

自 v0.8.5 版本起可用

有时候，不仅为单个集合创建快照，而且为整个存储（包括集合别名）创建快照可能会很方便。 Qdrant 为此也提供了一个专门的 API。它与集合级别的快照类似，但不需要 collection_name。

创建完整存储快照

POST /snapshots

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

client.create_full_snapshot()

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.createFullSnapshot();

use qdrant_client::Qdrant;

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.create_full_snapshot().await?;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;

QdrantClient client =
    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client.createFullSnapshotAsync().get();

using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.CreateFullSnapshotAsync();

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
	Host: "localhost",
	Port: 6334,
})

client.CreateFullSnapshot(context.Background())

删除完整存储快照

自 v1.0.0 起可用

DELETE /snapshots/{snapshot_name}

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

client.delete_full_snapshot(snapshot_name="{snapshot_name}")

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.deleteFullSnapshot("{snapshot_name}");

use qdrant_client::Qdrant;

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.delete_full_snapshot("{snapshot_name}").await?;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;

QdrantClient client =
    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client.deleteFullSnapshotAsync("{snapshot_name}").get();

using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.DeleteFullSnapshotAsync("{snapshot_name}");

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
	Host: "localhost",
	Port: 6334,
})

client.DeleteFullSnapshot(context.Background(), "{snapshot_name}")

列出完整存储快照

GET /snapshots

from qdrant_client import QdrantClient

client = QdrantClient("localhost", port=6333)

client.list_full_snapshots()

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.listFullSnapshots();

use qdrant_client::Qdrant;

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.list_full_snapshots().await?;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;

QdrantClient client =
    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());

client.listFullSnapshotAsync().get();

using Qdrant.Client;

var client = new QdrantClient("localhost", 6334);

await client.ListFullSnapshotsAsync();

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
	Host: "localhost",
	Port: 6334,
})

client.ListFullSnapshots(context.Background())

下载完整存储快照

GET /snapshots/{snapshot_name}

恢复完整存储快照

恢复快照只能在启动时通过Qdrant CLI进行。

例如：

./qdrant --storage-snapshot /snapshots/full-snapshot-2022-07-18-11-20-51.snapshot

存储

创建、上传和恢复的快照存储为.snapshot文件。默认情况下，它们存储在本地文件系统上。您也可以配置使用S3存储服务来存储它们。

本地文件系统

默认情况下，快照存储在./snapshots或使用我们的Docker镜像时存储在/qdrant/snapshots。

目标目录可以通过配置来控制：

storage:
  # Specify where you want to store snapshots.
  snapshots_path: ./snapshots

或者，您可以使用环境变量 QDRANT__STORAGE__SNAPSHOTS_PATH=./snapshots。

自 v1.3.0 起可用

在创建快照时，临时文件默认放置在配置的存储目录中。如果容量有限或网络附加磁盘速度较慢，您可以指定一个单独的位置用于临时文件：

storage:
  # Where to store temporary files
  temp_path: /tmp

S3

自 v1.10.0 起可用

与其将快照存储在本地文件系统中，您也可以配置为将快照存储在S3兼容的存储服务中。要启用此功能，您必须在配置文件中进行配置。

例如，配置为AWS S3：

storage:
  snapshots_config:
    # Use 's3' to store snapshots on S3
    snapshots_storage: s3

    s3_config:
      # Bucket name
      bucket: your_bucket_here

      # Bucket region (e.g. eu-central-1)
      region: your_bucket_region_here

      # Storage access key
      # Can be specified either here or in the `QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY` environment variable.
      access_key: your_access_key_here

      # Storage secret key
      # Can be specified either here or in the `QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__SECRET_KEY` environment variable.
      secret_key: your_secret_key_here

      # S3-Compatible Storage URL
      # Can be specified either here or in the `QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ENDPOINT_URL` environment variable.
      endpoint_url: your_url_here