> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# filesystem_cache_* 세션 설정

> filesystem_cache_*로 생성된 그룹에 대한 ClickHouse 세션 설정입니다.

export const CloudOnlyBadge = () => {
  return <div className="cloudBadge">
            <div className="cloudIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path fillRule="evenodd" clipRule="evenodd" d="M5.33395 12.6667H12.3739C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00004 12.3739 8.00004H12.0839V7.33337C12.0839 5.12671 10.2906 3.33337 8.08395 3.33337C6.09928 3.33337 4.45395 4.78537 4.14195 6.68204C2.55728 6.76271 1.29395 8.06204 1.29395 9.66671C1.29395 11.3234 2.63728 12.6667 4.29395 12.6667H5.33395Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'ClickHouse Cloud 전용'}
        </div>;
};

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["버전", "기본값", "설명"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        버전 이력
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>유형</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>기본값</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          재시작 없이 변경 가능
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

이 설정은 [system.settings](/ko/reference/system-tables/settings)에서 확인할 수 있으며, [source](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp)로부터 자동 생성됩니다.

<div id="filesystem_cache_allow_background_download">
  ## filesystem\_cache\_allow\_background\_download
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.11"},{"label": "1"},{"label": "쿼리별로 파일 시스템 캐시의 백그라운드 다운로드를 제어하는 새로운 설정입니다."}]}]} />

원격 스토리지에서 읽은 데이터에 대해 파일 시스템 캐시가 백그라운드 다운로드를 큐에 추가하도록 허용합니다. 비활성화하면 다운로드는 현재 쿼리/세션의 포그라운드에서 수행됩니다.

<div id="filesystem_cache_boundary_alignment">
  ## filesystem\_cache\_boundary\_alignment
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "0"},{"label": "새로운 설정"}]}]} />

파일 시스템 캐시 경계 정렬입니다. 이 설정은 디스크에서 읽지 않는 경우에만 적용됩니다(예: 원격 테이블 엔진/테이블 함수의 캐시에는 적용되지만, MergeTree 테이블의 저장소 구성에는 적용되지 않습니다). 값이 0이면 정렬하지 않습니다.

<div id="filesystem_cache_enable_background_download_during_fetch">
  ## filesystem\_cache\_enable\_background\_download\_during\_fetch
</div>

<CloudOnlyBadge />

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "1"},{"label": "새로운 설정"}]}]} />

ClickHouse Cloud에서만 적용됩니다. 파일 시스템 캐시에서 공간을 예약하기 위해 캐시 잠금을 획득할 때까지의 대기 시간

<div id="filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage">
  ## filesystem\_cache\_enable\_background\_download\_for\_metadata\_files\_in\_packed\_storage
</div>

<CloudOnlyBadge />

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "1"},{"label": "새로운 설정"}]}]} />

ClickHouse Cloud에서만 적용됩니다. 파일 시스템 캐시에서 공간을 예약하기 위해 캐시 잠금을 획득할 때까지의 대기 시간

<div id="filesystem_cache_max_download_size">
  ## filesystem\_cache\_max\_download\_size
</div>

<SettingsInfoBlock type="UInt64" default_value="137438953472" />

단일 쿼리에서 다운로드할 수 있는 원격 파일 시스템 캐시의 최대 크기

<div id="filesystem_cache_name">
  ## filesystem\_cache\_name
</div>

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": ""},{"label": "stateless 테이블 엔진이나 데이터 레이크에서 사용할 파일 시스템 캐시 이름"}]}]} />

stateless 테이블 엔진이나 데이터 레이크에서 사용할 파일 시스템 캐시 이름

<div id="filesystem_cache_prefer_bigger_buffer_size">
  ## filesystem\_cache\_prefer\_bigger\_buffer\_size
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "1"},{"label": "새로운 설정"}]}]} />

파일 시스템 캐시가 활성화된 경우, 캐시 성능을 저하시키는 작은 file segment의 쓰기를 방지하기 위해 더 큰 버퍼 크기를 사용하는 것이 바람직합니다. 반면, 이 설정을 활성화하면 메모리 사용량이 증가할 수 있습니다.

<div id="filesystem_cache_reserve_space_wait_lock_timeout_milliseconds">
  ## filesystem\_cache\_reserve\_space\_wait\_lock\_timeout\_milliseconds
</div>

<SettingsInfoBlock type="UInt64" default_value="1000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "1000"},{"label": "파일 시스템 캐시에서 공간을 예약하기 위해 캐시 잠금을 획득할 때까지 대기하는 시간"}]}]} />

파일 시스템 캐시에서 공간을 예약하기 위해 캐시 잠금을 획득할 때까지 대기하는 시간

<div id="filesystem_cache_segments_batch_size">
  ## filesystem\_cache\_segments\_batch\_size
</div>

<SettingsInfoBlock type="UInt64" default_value="20" />

읽기 버퍼가 캐시에서 한 번에 요청할 수 있는 파일 세그먼트 배치 크기의 제한입니다. 값이 너무 낮으면 캐시에 대한 요청이 과도하게 많아지고, 너무 크면 캐시에서의 eviction이 느려질 수 있습니다.

<div id="filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit">
  ## filesystem\_cache\_skip\_download\_if\_exceeds\_per\_query\_cache\_write\_limit
</div>

**별칭**: `skip_download_if_exceeds_query_cache`

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "1"},{"label": "설정 skip_download_if_exceeds_query_cache_limit의 이름 변경"}]}]} />

쿼리 캐시 크기 제한을 초과하면 원격 파일 시스템에서의 다운로드를 건너뜁니다

<div id="filesystem_cache_verbose_logging">
  ## filesystem\_cache\_verbose\_logging
</div>

<SettingsInfoBlock type="Bool" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "0"},{"label": "이전에는 로그 레벨이 허용하면 항상 출력되던 파일 시스템 캐시 읽기 버퍼의 버퍼 리필당 TEST 수준 로그 메시지를 제어하는 새로운 설정입니다."}]}]} />

파일 시스템 캐시 버퍼를 리필할 때마다 `TEST` 수준의 로그 메시지(읽기 상태, 남은 읽기 크기, 읽은 바이트 수)를 출력합니다. 디버깅 용도로만 사용하십시오. 메시지는 읽기마다 한 번 포맷되므로, 작은 캐시 읽기를 많이 수행하는 쿼리에서 이 설정을 활성화하면 로깅 오버헤드가 크게 증가합니다. 메시지는 어차피 로그 레벨이 `test`일 때만 표시됩니다(`send_logs_level` 참조).

<div id="filesystem_cache_wait_for_concurrent_download_timeout_milliseconds">
  ## filesystem\_cache\_wait\_for\_concurrent\_download\_timeout\_milliseconds
</div>

<SettingsInfoBlock type="UInt64" default_value="1000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "1000"},{"label": "동시 쿼리가 파일 시스템 캐시에 다운로드 중인 파일 세그먼트를 읽기 작업이 대기하는 시간을 제한하는 새로운 설정입니다. 시간 초과 시 읽기 작업은 무기한 대기하는 대신 캐시를 우회합니다. 이전 값 60000은 기존 동작(다운로더에서 전체 60초 대기 사이클 1회)에 해당합니다."}]}]} />

동시 쿼리가 파일 시스템 캐시에 다운로드 중인 파일 세그먼트를 대기하는 최대 시간입니다. 시간 초과에 도달하면 읽기 작업은 해당 범위에서 파일 시스템 캐시를 우회하고 원격 스토리지에서 직접 읽으며, 동시 다운로드는 계속 캐시를 채웁니다. 값 `0`은 전혀 대기하지 않음을 의미합니다. 필요한 범위가 아직 다운로드되지 않은 경우 즉시 캐시를 우회합니다. 이 값을 낮추면 원격 스토리지에 대한 추가 요청이 발생하는 대신, 다른 쿼리의 다운로드 속도를 기다리게 되는 캐시 적중 읽기의 테일 지연 시간을 제한할 수 있습니다.