Communicate with OpenSearch

Cloud_ Ghost·2025년 9월 8일

opensearch

목록 보기
19/23

https://docs.opensearch.org/latest/getting-started/communicate/

OpenSearch와 통신하기

REST API 또는 OpenSearch 언어 클라이언트 중 하나를 사용하여 OpenSearch와 통신할 수 있습니다. 이 페이지에서는 OpenSearch REST API를 소개합니다. 프로그래밍 언어에서 OpenSearch와 통신해야 하는 경우 사용 가능한 클라이언트 목록은 클라이언트 섹션을 참조하세요.

OpenSearch REST API

OpenSearch 클러스터와 상호 작용할 때는 많은 유연성을 제공하는 REST API를 사용합니다. REST API를 통해 대부분의 OpenSearch 설정 변경, 인덱스 수정, 클러스터 상태 확인, 통계 조회 등 거의 모든 작업을 수행할 수 있습니다. cURL과 같은 클라이언트나 HTTP 요청을 보낼 수 있는 모든 프로그래밍 언어를 사용할 수 있습니다.

터미널이나 OpenSearch Dashboards의 Dev Tools 콘솔에서 HTTP 요청을 보낼 수 있습니다.

터미널에서 요청 보내기

터미널에서 cURL 요청을 보낼 때 요청 형식은 Security 플러그인을 사용하는지 여부에 따라 달라집니다. 예로 Cluster Health API에 대한 요청을 고려해보겠습니다.

Security 플러그인을 사용하지 않는 경우 다음 요청을 보내세요:

curl -X GET "http://localhost:9200/_cluster/health"

Security 플러그인을 사용하는 경우 요청에 사용자명과 비밀번호를 제공하세요:

curl -X GET "https://localhost:9200/_cluster/health" -ku admin:<커스텀-관리자-비밀번호>

기본 사용자명은 admin이고, 비밀번호는 docker-compose.yml 파일의 OPENSEARCH_INITIAL_ADMIN_PASSWORD=<커스텀-관리자-비밀번호> 설정에 지정됩니다.

OpenSearch는 일반적으로 기본적으로 플랫 JSON 형식으로 응답을 반환합니다. 사람이 읽기 쉬운 응답 본문을 위해서는 pretty 쿼리 매개변수를 제공하세요:

curl -X GET "https://localhost:9200/_cluster/health?pretty"

pretty 및 기타 유용한 쿼리 매개변수에 대한 자세한 정보는 "공통 REST 매개변수"를 참조하세요.

본문이 포함된 요청의 경우 Content-Type 헤더를 지정하고 -d(data) 옵션에서 요청 페이로드를 제공하세요:

curl -X GET "https://localhost:9200/students/_search?pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  }
}'

Dev Tools에서 요청 보내기

OpenSearch Dashboards의 Dev Tools 콘솔은 cURL 명령과 비교하여 REST 요청을 형식화하는 더 간단한 구문을 사용합니다. Dev Tools에서 요청을 보내려면 다음 단계를 사용하세요:

  1. OpenSearch 클러스터를 실행하는 동일한 호스트의 웹 브라우저에서 https://localhost:5601/을 열어 OpenSearch Dashboards에 접근하세요. 기본 사용자명은 admin이고, 비밀번호는 docker-compose.yml 파일의 OPENSEARCH_INITIAL_ADMIN_PASSWORD=<커스텀-관리자-비밀번호> 설정에 지정됩니다.

  2. 상단 메뉴 바에서 Management > Dev Tools로 이동하세요.

  3. 콘솔의 왼쪽 창에서 다음 요청을 입력하세요:

GET _cluster/health
  1. 요청 오른쪽 위의 삼각형 아이콘을 선택하여 쿼리를 제출하세요. Ctrl+Enter(Mac 사용자는 Cmd+Enter)를 눌러서도 요청을 제출할 수 있습니다. 쿼리 제출을 위한 OpenSearch Dashboards 콘솔 사용에 대한 자세한 내용은 "콘솔에서 쿼리 실행하기"를 참조하세요.

다음 섹션들과 대부분의 OpenSearch 문서에서 요청은 Dev Tools 콘솔 형식으로 제시됩니다.

문서 인덱싱

OpenSearch 인덱스에 JSON 문서를 추가하려면(즉, 문서를 인덱싱하려면) 다음 헤더와 함께 HTTP 요청을 보냅니다:

PUT https://<호스트>:<포트>/<인덱스-이름>/_doc/<문서-ID>

예를 들어, 학생을 나타내는 문서를 인덱싱하려면 다음 요청을 보낼 수 있습니다:

PUT /students/_doc/1
{
  "name": "홍길동",
  "gpa": 3.89,
  "grad_year": 2022
}

앞의 요청을 보내면 OpenSearch가 students라는 인덱스를 생성하고 수집된 문서를 인덱스에 저장합니다. 문서에 대한 ID를 제공하지 않으면 OpenSearch가 문서 ID를 생성합니다. 앞의 요청에서 문서 ID는 학생 ID(1)로 지정되었습니다.

인덱싱에 대한 자세한 내용은 "인덱스 관리"를 참조하세요.

동적 매핑

문서를 인덱싱할 때 OpenSearch는 문서에 제출된 JSON 유형에서 필드 유형을 추론합니다. 이 과정을 동적 매핑이라고 합니다. 자세한 정보는 "동적 매핑"을 참조하세요.

추론된 필드 유형을 보려면 _mapping 엔드포인트에 요청을 보내세요:

GET /students/_mapping

OpenSearch는 각 필드의 필드 유형으로 응답합니다:

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "long"
        },
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        }
      }
    }
  }
}

OpenSearch는 숫자 필드를 float과 long 유형으로 매핑했습니다. OpenSearch가 name 텍스트 필드를 text로 매핑하고 keyword로 매핑된 name.keyword 하위 필드를 추가했습니다. text로 매핑된 필드는 분석되고(소문자화되고 용어로 분할됨) 전체 텍스트 검색에 사용할 수 있습니다. keyword로 매핑된 필드는 정확한 용어 검색에 사용됩니다.

OpenSearch는 grad_year 필드를 long으로 매핑했습니다. 대신 date 유형으로 매핑하려면 인덱스를 삭제한 다음 매핑을 명시적으로 지정하여 다시 생성해야 합니다. 매핑을 명시적으로 지정하는 방법에 대한 지침은 "인덱스 매핑 및 설정"을 참조하세요.

문서 검색

문서에 대한 검색을 실행하려면 검색할 인덱스와 문서를 일치시키는 데 사용할 쿼리를 지정합니다. 가장 간단한 쿼리는 인덱스의 모든 문서와 일치하는 match_all 쿼리입니다:

GET /students/_search
{
  "query": {
    "match_all": {}
  }
}

OpenSearch는 인덱싱된 문서를 반환합니다:

{
  "took": 12,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "students",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "홍길동",
          "gpa": 3.89,
          "grad_year": 2022
        }
      }
    ]
  }
}

검색에 대한 자세한 정보는 "데이터 검색"을 참조하세요.

문서 업데이트

OpenSearch에서 문서는 불변입니다. 그러나 문서를 검색하고, 정보를 업데이트하고, 다시 인덱싱하여 문서를 업데이트할 수 있습니다. Index Document API를 사용하여 전체 문서를 업데이트할 수 있으며, 문서의 모든 기존 필드와 추가된 필드에 대한 값을 제공합니다. 예를 들어, gpa 필드를 업데이트하고 이전에 인덱싱된 문서에 address 필드를 추가하려면 다음 요청을 보내세요:

PUT /students/_doc/1
{
  "name": "홍길동",
  "gpa": 3.91,
  "grad_year": 2022,
  "address": "서울시 강남구"
}

또는 Update Document API를 호출하여 문서의 일부를 업데이트할 수 있습니다:

POST /students/_update/1/
{
  "doc": {
    "gpa": 3.91,
    "address": "서울시 강남구"
  }
}

부분 문서 업데이트에 대한 자세한 정보는 "Update Document API"를 참조하세요.

문서 삭제

문서를 삭제하려면 삭제 요청을 보내고 문서 ID를 제공하세요:

DELETE /students/_doc/1

인덱스 삭제

인덱스를 삭제하려면 다음 요청을 보내세요:

DELETE /students

인덱스 매핑 및 설정

OpenSearch 인덱스는 매핑과 설정으로 구성됩니다:

  • 매핑은 필드의 컬렉션과 해당 필드의 유형입니다. 자세한 정보는 "매핑 및 필드 유형"을 참조하세요.
  • 설정에는 인덱스 이름, 생성 날짜, 샤드 수와 같은 인덱스 데이터가 포함됩니다. 자세한 정보는 "OpenSearch 구성"을 참조하세요.

한 요청에서 매핑과 설정을 지정할 수 있습니다. 예를 들어, 다음 요청은 인덱스 샤드 수를 지정하고 name 필드를 text로, grad_year 필드를 date로 매핑합니다:

PUT /students
{
  "settings": {
    "index.number_of_shards": 1
  }, 
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "grad_year": {
        "type": "date"
      }
    }
  }
}

이제 이전 섹션에서 인덱싱한 것과 동일한 문서를 인덱싱할 수 있습니다:

PUT /students/_doc/1
{
  "name": "홍길동",
  "gpa": 3.89,
  "grad_year": 2022
}

인덱스 필드의 매핑을 보려면 다음 요청을 보내세요:

GET /students/_mapping

OpenSearch는 지정된 유형에 따라 name과 grad_year 필드를 매핑하고 gpa 필드의 필드 유형을 추론했습니다:

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "date"
        },
        "name": {
          "type": "text"
        }
      }
    }
  }
}

필드가 생성되면 해당 유형을 변경할 수 없습니다. 필드 유형을 변경하려면 인덱스를 삭제하고 새로운 매핑으로 다시 생성해야 합니다.

추가 읽기

  • OpenSearch REST API에 대한 정보는 REST API 참조를 참조하세요.
  • OpenSearch 언어 클라이언트에 대한 정보는 클라이언트를 참조하세요.
  • 매핑에 대한 정보는 "매핑 및 필드 유형"을 참조하세요.
  • 설정에 대한 정보는 "OpenSearch 구성"을 참조하세요.

다음 단계

수집 옵션에 대해 알아보려면 "OpenSearch로 데이터 수집하기"를 참조하세요.

profile
Cloud_ Ghost
행복합시다~
이전 포스트

Ingest your data into OpenSearch

다음 포스트

Installation quickstart

0개의 댓글