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

> Использование S3-совместимого объектного хранилища SeaweedFS с ClickHouse

# Использование SeaweedFS

export const CloudNotSupportedBadge = () => {
  return <a href="https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility#list-of-unsupported-features" className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Не поддерживается в ClickHouse Cloud
        </a>;
};

<CloudNotSupportedBadge />

<Note>
  Эта страница не применима к [ClickHouse Cloud](https://clickhouse.com/cloud). Описанная здесь возможность недоступна в сервисах ClickHouse Cloud.
  Дополнительные сведения см. в руководстве ClickHouse [Cloud Compatibility](/docs/ru/products/cloud/guides/cloud-compatibility).
</Note>

Табличная функция `s3` и тип диска `S3` в ClickHouse совместимы с [SeaweedFS](https://github.com/seaweedfs/seaweedfs) — распределённым хранилищем объектов с открытым исходным кодом и S3-совместимым шлюзом. SeaweedFS нативно поддерживает запросы в стиле path-style, поэтому самоуправляемое хранилище работает без wildcard DNS. SeaweedFS также поддерживает таблицы Iceberg: в его бакетах таблиц данные хранятся в виде файлов Parquet, а встроенный REST-каталог Iceberg предоставляет метаданные таблиц. О выполнении запросов к ним через ту же конечную точку см. [руководство по каталогу SeaweedFS](/docs/ru/guides/use-cases/data-warehousing/seaweedfs-catalog).

Используйте [SeaweedFS 4.42](https://github.com/seaweedfs/seaweedfs/releases/tag/4.42) или более новую версию. В более ранних версиях объект может быть удалён, если коммит его записи происходит одновременно с удалением родительской папки как пустой. Сразу после успешной записи это проявляется сообщением `Object ... suddenly disappeared`.

<div id="running-seaweedfs-locally">
  ## Запуск SeaweedFS на локальной машине
</div>

Для локального тестирования создайте файл `s3config.json` с учетными данными S3:

```json theme={null}
{
  "identities": [
    {
      "name": "analyst",
      "credentials": [
        {
          "accessKey": "your_access_key_id",
          "secretKey": "your_secret_access_key"
        }
      ],
      "actions": ["Admin", "Read", "Write", "List", "Tagging"]
    }
  ]
}
```

Затем запустите весь стек SeaweedFS в одном контейнере — флаг `-bucket` создаст бакет при запуске:

```bash theme={null}
docker run -d --name seaweedfs -p 8333:8333 \
  -v "$(pwd)/s3config.json:/etc/seaweedfs/s3config.json" \
  chrislusf/seaweedfs:latest \
  mini -dir=/data -s3.config=/etc/seaweedfs/s3config.json -bucket=clickhouse
```

Конечная точка S3 доступна на порту 8333; прежде чем продолжить, дождитесь ответа:

```bash theme={null}
until curl -s -o /dev/null http://localhost:8333; do sleep 1; done
```

Дополнительные бакеты можно создать в любое время с помощью команды `echo "s3.bucket.create -name mybucket" | docker exec -i seaweedfs weed shell`.

По умолчанию запись подтверждается после передачи операционной системе. Чтобы перед подтверждением выполнять fsync каждой записи на диск, включите fsync для бакета:

```bash theme={null}
echo "fs.configure -locationPrefix=/buckets/clickhouse/ -fsync -apply" | \
  docker exec -i seaweedfs weed shell
```

<div id="s3-backed-mergetree">
  ## MergeTree с бэкендом S3
</div>

Конфигурация MergeTree с бэкендом S3 совместима после внесения незначительных изменений:

```xml theme={null}
<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>http://seaweedfs:8333/clickhouse/tables/</endpoint>
                <access_key_id>your_access_key_id</access_key_id>
                <secret_access_key>your_secret_access_key</secret_access_key>
                <region></region>
                <metadata_path>/var/lib/clickhouse/disks/s3/</metadata_path>
            </s3>
            <s3_cache>
                <type>cache</type>
                <disk>s3</disk>
                <path>/var/lib/clickhouse/disks/s3_cache/</path>
                <max_size>10Gi</max_size>
            </s3_cache>
        </disks>
        <policies>
            <s3_main>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3_main>
        </policies>
    </storage_configuration>
</clickhouse>
```

<Tip>
  Конечная точка содержит имя бакета (`clickhouse`), за которым следует префикс пути (`tables/`) для данных таблицы. SeaweedFS не требует указания региона, поэтому соответствующий тег можно оставить пустым. Замените `seaweedfs` на хост, на котором запущен шлюз S3.
</Tip>

Затем таблицы размещают данные в SeaweedFS с помощью политики хранения:

```sql theme={null}
CREATE TABLE trips (id UInt64, rider String, fare Float64)
ENGINE = MergeTree
ORDER BY id
SETTINGS storage_policy = 's3_main';
```

Чтобы локально кэшировать часто считываемые данные, создайте таблицу с `SETTINGS disk = 's3_cache'` — определённый выше кэш-диск является обёрткой для S3-диска.

<div id="the-s3-table-function">
  ## Табличная функция s3
</div>

Табличная функция `s3` читает и записывает объекты через одну и ту же конечную точку:

```sql theme={null}
INSERT INTO FUNCTION s3(
    'http://seaweedfs:8333/clickhouse/sample/trips.parquet',
    'your_access_key_id',
    'your_secret_access_key',
    'Parquet'
)
SELECT number AS id, concat('rider_', toString(number % 10)) AS rider, number * 1.5 AS fare
FROM numbers(1000);

SELECT count()
FROM s3(
    'http://seaweedfs:8333/clickhouse/sample/*.parquet',
    'your_access_key_id',
    'your_secret_access_key',
    'Parquet'
);
```

Глоб-шаблоны позволяют читать несколько объектов.

<div id="backup-and-restore">
  ## Резервное копирование и восстановление
</div>

`BACKUP` и `RESTORE` поддерживают конечную точку SeaweedFS в качестве пункта назначения S3:

```sql theme={null}
BACKUP TABLE trips
TO S3('http://seaweedfs:8333/clickhouse/backups/trips1', 'your_access_key_id', 'your_secret_access_key');

--- DROP TABLE trips;

RESTORE TABLE trips
FROM S3('http://seaweedfs:8333/clickhouse/backups/trips1', 'your_access_key_id', 'your_secret_access_key');
```