Lookups API

Lookups API

Apache Druid의 lookup을 구성·업데이트·조회·관리하는 API 엔드포인트를 다룹니다. 벌크 업데이트부터 개별 lookup 상태 확인까지 설명해요.

출처: 문서

본문

이 문서는 Apache Druid의 lookup을 구성, 업데이트, 조회, 관리하기 위한 API 엔드포인트를 설명합니다.

Lookup 구성하기

벌크 업데이트 (Bulk update)

lookup은 JSON 객체를 /druid/coordinator/v1/lookups/config에 POST해서 벌크 업데이트할 수 있어요. JSON 객체의 형식은 다음과 같습니다.

{
    "<tierName>": {
        "<lookupName>": {
          "version": "<version>",
          "lookupExtractorFactory": {
            "type": "<someExtractorFactoryType>",
            "<someExtractorField>": "<someExtractorValue>"
          }
        }
    }
}

"version"은 사용자가 할당하는 임의의 문자열이라는 점을 기억하세요. 기존 lookup을 업데이트할 때는 사전순으로 더 높은(lexicographically higher) 버전을 지정해야 합니다.

예를 들어, config는 다음과 같은 형태일 수 있어요.

{
  "__default": {
    "country_code": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "77483": "United States"
        }
      }
    },
    "site_id": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "cachedNamespace",
        "extractionNamespace": {
          "type": "jdbc",
          "connectorConfig": {
            "createTables": true,
            "connectURI": "jdbc:mysql:\/\/localhost:3306\/druid",
            "user": "druid",
            "password": "diurd"
          },
          "table": "lookupTable",
          "keyColumn": "country_id",
          "valueColumn": "country_name",
          "tsColumn": "timeColumn"
        },
        "firstCacheTimeout": 120000,
        "injective": true
      }
    },
    "site_id_customer1": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "847632": "Internal Use Only"
        }
      }
    },
    "site_id_customer2": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "AHF77": "Home"
        }
      }
    }
  },
  "realtime_customer1": {
    "country_code": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "77483": "United States"
        }
      }
    },
    "site_id_customer1": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "847632": "Internal Use Only"
        }
      }
    }
  },
  "realtime_customer2": {
    "country_code": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "77483": "United States"
        }
      }
    },
    "site_id_customer2": {
      "version": "v0",
      "lookupExtractorFactory": {
        "type": "map",
        "map": {
          "AHF77": "Home"
        }
      }
    }
  }
}

맵에 있는 모든 항목은 기존 항목을 UPDATE합니다. 삭제되는 항목은 없어요.

Lookup 업데이트

/druid/coordinator/v1/lookups/config/{tier}/{id}로 특정 lookup extractor factory에 POST하면 해당 extractor factory를 생성하거나 업데이트합니다.

예를 들어 /druid/coordinator/v1/lookups/config/realtime_customer1/site_id_customer1로의 POST는 다음을 포함할 수 있습니다.

{
  "version": "v1",
  "lookupExtractorFactory": {
    "type": "map",
    "map": {
      "847632": "Internal Use Only"
    }
  }
}

이것은 realtime_customer1 티어의 site_id_customer1 lookup을 위 정의로 교체합니다.

lookup extractor factory를 업데이트할 때마다 고유한 버전 식별자를 할당하세요. 그렇지 않으면 호출이 실패합니다.

모든 lookup 가져오기

/druid/coordinator/v1/lookups/config/all에 GET하면 모든 티어의 알려진 모든 lookup 스펙을 반환합니다.

Lookup 가져오기

특정 lookup extractor factory에 대한 GET은 /druid/coordinator/v1/lookups/config/{tier}/{id}로 수행됩니다.

앞의 예시를 사용하면, /druid/coordinator/v1/lookups/config/realtime_customer2/site_id_customer2에 GET하면 다음을 반환해야 합니다.

{
  "version": "v1",
  "lookupExtractorFactory": {
    "type": "map",
    "map": {
      "AHF77": "Home"
    }
  }
}

Lookup 삭제

/druid/coordinator/v1/lookups/config/{tier}/{id}에 DELETE하면 클러스터에서 해당 lookup을 제거합니다. 그것이 티어의 마지막 lookup이라면 티어도 함께 삭제됩니다.

티어 삭제

/druid/coordinator/v1/lookups/config/{tier}에 DELETE하면 클러스터에서 해당 티어를 제거합니다.

티어 이름 목록

/druid/coordinator/v1/lookups/config에 GET하면 동적 구성에 알려진 티어 이름 목록을 반환합니다. 동적 구성에 알려진 것 외에 클러스터에서 현재 활성화된 티어 목록까지 찾으려면 /druid/coordinator/v1/lookups/config?discover=true처럼 discover=true 파라미터를 추가할 수 있어요.

Lookup 이름 목록

/druid/coordinator/v1/lookups/config/{tier}에 GET하면 해당 티어의 알려진 lookup 이름 목록을 반환합니다.

이 엔드포인트들은 구성된 lookup이 Historical 같은 lookup 사용 프로세스로 전파되는 상태를 파악하는 데 사용할 수 있어요.

Lookup 상태 (Lookup status)

모든 lookup의 로드 상태 목록

GET /druid/coordinator/v1/lookups/status (선택적 쿼리 파라미터 detailed)

티어 안의 lookup의 로드 상태 목록

GET /druid/coordinator/v1/lookups/status/{tier} (선택적 쿼리 파라미터 detailed)

단일 lookup의 로드 상태 목록

GET /druid/coordinator/v1/lookups/status/{tier}/{lookup} (선택적 쿼리 파라미터 detailed)

모든 프로세스의 lookup 상태 목록

GET /druid/coordinator/v1/lookups/nodeStatus — 선택적 쿼리 파라미터 discover를 사용해 다른 Druid 노드가 광고하는 티어를 찾거나, 기본적으로 모든 구성된 lookup 티어를 반환합니다. 기본 응답에는 각 노드에서 로드되었거나 로드 중이거나 드롭 중인 lookup이 티어별로, 완전한 lookup 스펙과 함께 포함됩니다. 선택적 쿼리 파라미터 detailed=false를 추가하면 완전한 스펙 대신 lookup의 version만 포함합니다.

티어 안 프로세스의 lookup 상태 목록

GET /druid/coordinator/v1/lookups/nodeStatus/{tier}

단일 프로세스의 lookup 상태 목록

GET /druid/coordinator/v1/lookups/nodeStatus/{tier}/{host:port}

내부 API (Internal API)

Peon, Router, Broker, Historical 프로세스는 모두 lookup 구성을 사용할 수 있어요. 이 프로세스들이 자신의 lookup을 나열/로드/드롭하는 데 사용하는 내부 API가 /druid/listen/v1/lookups에서 시작됩니다. 이들은 클러스터 전역 동적 구성과 동일한 반환 값 규칙을 따릅니다. 다음 엔드포인트는 디버깅 목적으로만 사용할 수 있고 그 외에는 사용할 수 없어요.

Lookup 가져오기

프로세스의 /druid/listen/v1/lookups에 GET하면 현재 프로세스에서 활성화된 모든 lookup의 JSON 맵을 반환합니다. 반환 값은 lookup과 그 extractor factory의 JSON 맵이에요.

{
  "site_id_customer2": {
    "version": "v1",
    "lookupExtractorFactory": {
      "type": "map",
      "map": {
        "AHF77": "Home"
      }
    }
  }
}

Lookup 가져오기

프로세스의 /druid/listen/v1/lookups/some_lookup_name에 GET하면 some_lookup_name으로 식별되는 lookup의 LookupExtractorFactory를 반환합니다. 반환 값은 factory의 JSON 표현입니다.

{
  "version": "v1",
  "lookupExtractorFactory": {
    "type": "map",
    "map": {
      "AHF77": "Home"
    }
  }
}

더 알아보기 (Learn more)

• lookup 구성의 전체 개념은 lookups 문서를 참고하세요.
• Coordinator API 전반은 data-management 및 관련 API 문서에서 확인해 보세요.