별칭 관리 API

별칭 관리 API (Manage Aliases API)

1.0 버전에서 도입되었어요. 별칭 관리 API는 여러 인덱스 별칭 작업을 하나의 원자적(atomic) 트랜잭션으로 처리해요. 여러 별칭을 추가하거나 제거해야 할 때, 별칭을 한 인덱스에서 다른 인덱스로 전환할 때, 또는 별칭을 관리하면서 동시에 인덱스를 삭제해야 할 때 이 API를 사용하세요. 이 API는 actions 배열을 받아서, 반드시 원자적으로 수행되어야 하는 복잡한 별칭 작업에 아주 적합해요.

이 API는 한 번에 단일 별칭을 처리하고 다른 요청 파라미터를 사용하는 Create or update alias API와는 구별돼요. 여러 별칭이나 인덱스가 관련된 일괄 작업과 원자적 트랜잭션에는 별칭 관리 API를 사용하세요.

인덱스 별칭에 대한 개념적 설명(사용 사례와 예제 포함)은 Index aliases 문서를 참고하세요.

출처: 문서

본문

엔드포인트 (Endpoints)

POST _aliases

쿼리 파라미터 (Query parameters)

아래 표는 사용 가능한 쿼리 파라미터를 정리한 거예요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
cluster_manager_timeout Time 클러스터 매니저 노드의 응답을 기다리는 시간. 기본값은 30s예요.
timeout Time 클러스터의 응답을 기다리는 시간. 기본값은 30s예요.

요청 본문 필드 (Request body fields)

아래 표는 사용 가능한 요청 본문 필드를 정리한 거예요.

필드 데이터 타입 설명 필수 여부
actions Array 인덱스에 수행하려는 작업의 집합. 유효한 옵션은 add, remove, remove_index예요. 배열에는 최소한 하나의 작업이 있어야 해요. 예
add N/A 지정한 인덱스에 별칭을 추가해요. 아니요
remove N/A 지정한 인덱스에서 별칭을 제거해요. 아니요
remove_index N/A 인덱스를 삭제해요. 아니요
index String 별칭과 연결하려는 인덱스의 이름. 와일드카드 표현식을 지원해요. 본문에 indices 필드를 제공하지 않으면 예
indices Array 별칭과 연결하려는 인덱스 이름의 배열. 본문에 index 필드를 제공하지 않으면 예
alias String 별칭의 이름. 본문에 aliases 필드를 제공하지 않으면 예
aliases Array 별칭 이름의 배열. 본문에 alias 필드를 제공하지 않으면 예
filter Object 별칭과 함께 사용할 필터. 별칭이 인덱스의 필터링된 부분을 가리키게 해요. 아니요
is_hidden Boolean 와일드카드 표현식을 포함한 결과에서 별칭을 숨길지 여부. 아니요
must_exist Boolean 제거할 별칭이 반드시 존재해야 하는지 여부. 아니요
is_write_index Boolean 인덱스가 쓰기 인덱스(write index)가 되어야 하는지 여부. 별칭은 한 번에 하나의 쓰기 인덱스만 가질 수 있어요. 여러 인덱스에 연결된 별칭에 쓰기 요청이 제출되면 OpenSearch는 쓰기 인덱스에서만 요청을 실행해요. 중요한 점: 인덱스에 대해 is_write_index: true를 명시적으로 설정하지 않으면서 하나의 인덱스만 참조하는 별칭은, 다른 인덱스가 참조될 때까지 그 인덱스가 쓰기 인덱스처럼 동작해요. 그 시점부터는 쓰기 인덱스가 없게 되어 쓰기가 거부돼요. 아니요
routing String 특정 작업에 대해 샤드에 사용자 지정 값을 할당하는 데 사용. 아니요
index_routing String 인덱스 작업에 대해서만 샤드에 사용자 지정 값을 할당해요. 아니요
search_routing String 검색 작업에 대해서만 샤드에 사용자 지정 값을 할당해요. 아니요

예제: 별칭 추가 (Add an alias)

다음 요청은 application_logs_2024 인덱스를 가리키는 logs_current라는 별칭을 만들어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "application_logs_2024",
        "alias": "logs_current"
      }
    }
  ]
}

예제: 별칭 제거 (Remove an alias)

다음 요청은 application_logs_2024 인덱스에서 logs_current 별칭을 제거해요:

POST /_aliases
{
  "actions": [
    {
      "remove": {
        "index": "application_logs_2024",
        "alias": "logs_current"
      }
    }
  ]
}

예제: 별칭 이름 변경 (Rename an alias)

같은 요청에서 별칭을 한 인덱스에서 제거하고 다른 인덱스에 추가하면 원자적으로 이름을 변경할 수 있어요. 다음 예제는 primary_data 별칭을 dataset_v1에서 dataset_v2로 옮겨요:

POST /_aliases
{
  "actions": [
    {
      "remove": {
        "index": "dataset_v1",
        "alias": "primary_data"
      }
    },
    {
      "add": {
        "index": "dataset_v2",
        "alias": "primary_data"
      }
    }
  ]
}

별칭 작업은 원자적이라서, primary_data가 두 인덱스를 동시에 가리키거나 아무 인덱스도 가리키지 않는 순간은 존재하지 않아요.

예제: 여러 인덱스에 별칭 추가 (Add an alias to multiple indexes)

별도의 add 작업을 사용해 단일 별칭을 여러 인덱스와 연결할 수 있어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "products_electronics",
        "alias": "all_products"
      }
    },
    {
      "add": {
        "index": "products_clothing",
        "alias": "all_products"
      }
    },
    {
      "add": {
        "index": "products_books",
        "alias": "all_products"
      }
    }
  ]
}

예제: indices 배열 사용 (Use the indices array)

indices 배열을 사용하면 단일 작업에서 여러 인덱스를 지정할 수도 있어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "indices": ["products_electronics", "products_clothing", "products_books"],
        "alias": "all_products"
      }
    }
  ]
}

예제: 와일드카드 패턴 사용 (Use wildcard patterns)

와일드카드 패턴을 사용해 명명 규칙과 일치하는 여러 인덱스를 추가할 수 있어요. 다음 예제는 sales_2024로 시작하는 모든 인덱스에 대한 별칭을 만들어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "sales_2024_*",
        "alias": "current_year_sales"
      }
    }
  ]
}

이렇게 하면 생성 시점에 패턴과 일치하는 모든 인덱스를 포함하는 특정 시점(point-in-time) 별칭이 만들어져요. 나중에 새로 생성되어 패턴과 일치하는 인덱스는 자동으로 포함되지 않아요.

쓰기 인덱스를 지정하지 않고 여러 인덱스를 가리키는 별칭에 쓰는 것은 오류예요.

예제: 인덱스 교체 (Index swapping)

다운타임 없이 인덱스를 새 것으로 원자적으로 교체할 수 있어요. 재인덱싱(reindexing) 작업에 유용해요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "customer_data_new",
        "alias": "customer_data"
      }
    },
    {
      "remove_index": {
        "index": "customer_data_old"
      }
    }
  ]
}

이 작업은 단일 원자적 작업으로 새 인덱스를 별칭에 추가하고 기존 인덱스를 삭제해요.

예제: 필터링된 별칭 (Filtered aliases)

필터링된 별칭은 쿼리 필터를 적용해서 인덱스 안의 데이터를 분할할 수 있게 해줘요. 이를 통해 별도의 별칭 이름으로 접근할 수 있는 데이터의 집중된 하위 집합을 만들 수 있어요. 먼저 인덱스에 필요한 필드 매핑이 있는지 확인하세요:

PUT /user_activity
{
  "mappings": {
    "properties": {
      "user_type": {
        "type": "keyword"
      },
      "timestamp": {
        "type": "date"
      },
      "action": {
        "type": "keyword"
      }
    }
  }
}

그런 다음 필터링된 별칭을 만들어 데이터를 분할해요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "user_activity",
        "alias": "premium_users",
        "filter": {
          "term": {
            "user_type": "premium"
          }
        }
      }
    },
    {
      "add": {
        "index": "user_activity",
        "alias": "recent_activity",
        "filter": {
          "range": {
            "timestamp": {
              "gte": "now-7d"
            }
          }
        }
      }
    }
  ]
}

이 별칭들은 모든 검색, count, delete by query 작업에 지정한 필터를 자동으로 적용해요.

예제: 기본 라우팅 (Basic routing)

라우팅은 작업을 특정 샤드로 보내서, 쿼리해야 하는 샤드 수를 줄여 성능을 개선해요. 다음 예제는 라우팅 값이 있는 별칭을 만들어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "customer_orders",
        "alias": "region_east_orders",
        "routing": "east"
      }
    }
  ]
}

예제: 인덱스와 검색 작업의 별도 라우팅 (Separate routing for index and search operations)

인덱싱과 검색에 서로 다른 라우팅 값을 지정할 수 있어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "user_sessions",
        "alias": "mobile_sessions",
        "index_routing": "mobile",
        "search_routing": "mobile,tablet"
      }
    }
  ]
}

이 예제에서 별칭을 통해 인덱싱되는 모든 문서는 "mobile" 샤드로 가지만, 검색은 "mobile"과 "tablet" 샤드를 모두 쿼리할 수 있어요.

별칭 라우팅과 라우팅 파라미터를 모두 사용해 검색을 수행하면, OpenSearch는 두 값의 교집합을 사용해요. 예를 들어 GET /mobile_sessions/_search?routing=tablet,mobile로 검색하면, 별칭 라우팅(mobile,tablet)과 검색 파라미터(tablet,mobile)의 교집합이므로 "mobile" 라우팅 값만 사용돼요.

예제: 쓰기 인덱스 설정 (Setting a write index)

별칭이 여러 인덱스를 가리킬 때는 어떤 인덱스가 쓰기 작업을 처리할지 지정해야 해요.

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "logs_2024_01",
        "alias": "active_logs",
        "is_write_index": true
      }
    },
    {
      "add": {
        "index": "logs_2024_02",
        "alias": "active_logs",
        "is_write_index": false
      }
    }
  ]
}

이제 별칭에 쓸 수 있고, 모든 쓰기 작업은 logs_2024_01로 이동해요:

POST /active_logs/_doc
{
  "timestamp": "2024-01-15T10:30:00",
  "level": "INFO",
  "message": "Application started successfully"
}

예제: 쓰기 인덱스 전환 (Switch the write index)

어느 인덱스가 쓰기 인덱스 역할을 하는지 원자적으로 전환할 수 있어요:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "logs_2024_01",
        "alias": "active_logs",
        "is_write_index": false
      }
    },
    {
      "add": {
        "index": "logs_2024_02",
        "alias": "active_logs",
        "is_write_index": true
      }
    }
  ]
}

쓰기 인덱스를 사용할 때 다음 중요한 사항을 기억하세요:

  • 별칭은 한 번에 하나의 쓰기 인덱스만 가질 수 있어요.
  • 별칭이 지정된 쓰기 인덱스 없이 여러 인덱스를 가리키면 쓰기 작업이 거부돼요.
  • 단일 인덱스를 가리키는 별칭의 경우 그 인덱스가 자동으로 쓰기 인덱스 역할을 해요.

예제: must_exist 파라미터 사용 (Use the must_exist parameter)

OpenSearch는 remove 작업에 must_exist 파라미터를 제공해서, 존재하지 않는 별칭을 제거할 때의 오류 처리를 제어할 수 있어요:

POST /_aliases
{
  "actions": [
    {
      "remove": {
        "index": "application_logs_2024",
        "alias": "logs_current",
        "must_exist": true
      }
    }
  ]
}
  • must_exist: true - 별칭이 존재하지 않으면 오류를 던져요
  • must_exist: false - 별칭이 존재하지 않아도 조용히 성공해요
  • must_exist: null (기본값) - 지정한 별칭 중 아무것도 존재하지 않을 때만 오류를 던져요

예제 응답 (Example response)

모든 성공적인 별칭 작업은 동일한 응답 형식을 반환해요:

{
    "acknowledged": true
}

필요한 권한 (Required permissions)

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인하세요: indices:admin/aliases/get

인덱스 별칭에 대한 자세한 내용은 Index aliases 문서를 참고하세요.

더 알아보기 (Learn more)