Postman 사용법 / Elasticsearch CRUD및 인덱스 사용법

이 글은 Elasticsearch의 기본적인 이해를 한 사람을 위한 것이긴 하지만 기본적인 ES 용어들을 정리 했습니다. 모르는 용어가 나오면 아래 표를 참고 해주세요

Index (인덱스)	데이터를 저장하는 논리적인 단위. 데이터베이스의 "테이블"에 해당하며, 유사한 문서들의 집합.
Document (문서)	인덱스에 저장되는 개별 데이터 항목. 데이터베이스의 "행(row)" 또는 "레코드(record)"에 해당.
Field (필드)	문서 내의 키-값 쌍. 데이터베이스의 "컬럼(column)"에 해당.
Mapping (매핑)	인덱스의 데이터 구조를 정의한 스키마. 각 필드의 데이터 타입, 분석기 등을 설정.
Shard (샤드)	데이터를 분산 저장하기 위한 물리적 데이터 단위. 하나의 인덱스는 여러 샤드로 분리 가능.
Replica (복제본)	데이터의 고가용성과 장애 복구를 위해 샤드를 복제한 사본.
Cluster (클러스터)	하나 이상의 노드로 구성된 엘라스틱서치 시스템. 데이터 저장과 검색 작업을 수행하는 전체 시스템.
Node (노드)	클러스터 내의 하나의 서버 또는 인스턴스. 데이터를 저장하고 검색 요청을 처리.
Analyzer (분석기)	텍스트 데이터를 색인하거나 검색할 때 처리하는 모듈. 예: 토큰화, 소문자 변환.
Alias (별칭)	하나 이상의 인덱스를 가리키는 이름. 인덱스 이름을 추상화하여 유연성을 제공.
Query (쿼리)	데이터를 검색하거나 작업을 수행하기 위한 명령

Postman 사용법

1. 워크스페이스 생성

워크스페이스를 생성해줍니다. 템플릿을 추가하면 더 쉽게 사용할 수 있지만 저는 blank로 생성 했습니다.

2. Request 생성 방법

상단에 +를 누르면 Untitled Request가 새로 생성되고 HTTP를 선택하시면 됩니다.

3. Request 작성후 send

request의 method를 선택하고 (DELETE, PUT, POST, GET), 요청을 보낼 서버의 URL 주소를 입력 합니다.

그리고 요청에 필요한 정보가 있다면, Params, Body, Header, Authorization등을 이용해 입력 합니다.

Request 구성이 끝나면 Send 버튼을 누르시면 됩니다.

(request 구성 예시는 다음 챕터에서 나옵니다.)

4. 결과 확인

Body값을 통해 성공 실패 여부를 알수있습니다.

아래의 성공 코드가 어떻게 오냐에 따라서 성공 실패 여부와 원인등을 파악할 수 있습니다.

상태 코드	분류	설명	예시
200 OK	성공 (2xx)	요청이 성공적으로 처리됨.	검색 쿼리나 문서 조회가 성공한 경우.
201 Created	성공 (2xx)	요청으로 인해 새로운 리소스가 성공적으로 생성됨.	새 문서를 인덱스에 추가한 경우.
204 No Content	성공 (2xx)	요청이 성공했지만 반환할 데이터가 없음.	삭제 요청이 성공했으나 반환 데이터가 없는 경우.
400 Bad Request	클라이언트 오류 (4xx)	잘못된 요청.	잘못된 JSON 형식 또는 유효하지 않은 쿼리 파라미터를 전달한 경우.
401 Unauthorized	클라이언트 오류 (4xx)	인증이 필요한 요청에 인증 정보가 없거나 잘못됨.	보안 설정이 활성화된 클러스터에 인증 없이 접근한 경우.
403 Forbidden	클라이언트 오류 (4xx)	요청이 금지됨.	권한이 부족한 사용자가 특정 인덱스에 접근하려는 경우.
404 Not Found	클라이언트 오류 (4xx)	요청한 리소스(예: 인덱스나 문서)를 찾을 수 없음.	존재하지 않는 인덱스에서 검색을 시도한 경우.
409 Conflict	클라이언트 오류 (4xx)	요청이 리소스 상태와 충돌.	문서를 업데이트하려 했지만 버전 충돌이 발생한 경우.
429 Too Many Requests	클라이언트 오류 (4xx)	요청 속도가 너무 빨라 서버가 처리할 수 없음.	스로틀링 제한 초과.
500 Internal Server Error	서버 오류 (5xx)	서버에서 요청 처리 중 예기치 않은 오류가 발생함.	잘못된 스크립트가 실행된 경우.
503 Service Unavailable	서버 오류 (5xx)	서버가 요청을 처리할 준비가 되지 않음.	노드가 과부하 상태이거나 클러스터가 안정적이지 않은 경우.
413 Payload Too Large	클라이언트 오류 (4xx)	요청 본문이 서버에서 처리할 수 있는 크기를 초과.	너무 큰 데이터를 인덱싱하려고 한 경우.

실패시 우측 상단에 빨간색으로 상태코드가 나오고 에러 메세지를 통해 에러가 난 원인에 대해서 알수 있습니다.

성공시 우측 상단에 초록색으로 상태코드가 나오고 성공 결과에 대한 내용이 body로 넘어 옵니다.

Elasticsearch CRUD 및 인덱스 사용법

참고로 {{}} 안에 있는 값은 Postman에서 변수로 사용할 수 있는 기능입니다. 예를 들어, 호스트 값을 계속 동일하게 사용해야 하는 경우, Postman의 환경 변수나 글로벌 변수에 host를 등록하면, 모든 요청에서 http://{{host}}:9200과 같이 작성할 수 있습니다. 이렇게 하면 등록된 환경 변수에 따라 {{host}}가 자동으로 치환되어 실제 값(예: http://localhost:9200)으로 대체됩니다.

이 기능을 사용하면, 서버 주소가 변경되는 상황에서도 각 요청의 URL을 일일이 수정하지 않고, 한 번만 변수 값을 변경하여 모든 요청에서 반영되도록 관리할 수 있습니다.

그리고, 아래 예시는 기본포트인 9200을 사용했기 때문에 만약 다른 포트를 사용하신다면 호스트뒤에 포트값을 변경해 주세요

1. 인덱스 사용법

인덱스 생성

PUT

http://{{host}}:9200/[인덱스명]

인덱스 조회

GET

http://{{host}}:9200/_cat/indices

인덱스 삭제

DELETE

http://{{host}}:9200/[삭제할 인덱스 명]

매핑 추가

PUT

http://{{host}}:9200/[매핑 추가할 인덱스 명]/_mapping

타입 부분에는 표와 같은 타입들이 들어갈 수 있습니다.

카테고리	타입	설명	예시
문자열	text	분석 가능한 텍스트 데이터. 검색에 적합.	"This is a sample text"
	keyword	분석되지 않는 문자열. 정확히 일치하는 값 검색용.	"tag1", "user123"
숫자	long	64비트 정수.	123456
	integer	32비트 정수.	12345
	short	16비트 정수.	123
	byte	8비트 정수.	127
	double	64비트 부동소수점.	123.456
	float	32비트 부동소수점.	12.34
	half_float	16비트 부동소수점.	1.23
	scaled_float	소수점 이하 자릿수를 고정 (scaling_factor 필요).	12345.67 (scaling_factor: 100)
날짜/시간	date	날짜와 시간. ISO 8601 기본값 또는 사용자 지정 포맷.	"2024-12-16T12:34:56.789Z"
	date_nanos	나노초 정밀도를 지원하는 날짜와 시간.	"2024-12-16T12:34:56.123456789Z"
부울/이진 데이터	boolean	참/거짓 값을 저장.	true, false
	binary	Base64로 인코딩된 바이너리 데이터.	"U29tZSBkYXRh"
객체/중첩 데이터	object	JSON 객체 구조를 지원.	{"user": {"name": "Alice"}}
	nested	별도 문서처럼 저장되는 중첩 객체.	[{"tag": "tag1"}, {"tag": "tag2"}]
지리적 데이터	geo_point	위도와 경도 정보를 저장.	{"lat": 40.12, "lon": -71.34}
	geo_shape	지리적 도형 (다각형, 라인 등).	{"type": "polygon", "coordinates": [...]}
IP 주소	ip	IPv4 또는 IPv6 주소를 저장.	"192.168.1.1"
범위 데이터	integer_range	정수 범위.	{"gte": 10, "lte": 20}
	float_range	부동소수점 범위.	{"gte": 1.5, "lte": 10.5}
	long_range	긴 정수 범위.	{"gte": 1000, "lte": 5000}
	double_range	더블 범위.	{"gte": 0.1, "lte": 1.0}
	date_range	날짜 범위.	{"gte": "2023-01-01", "lte": "2023-12-31"}

{
    "properties":{
        "[필드명1]":{"type": "타입"},
        "[필드명2]":{"type": "타입"}
    }
}

매핑 확인

GET

http://{{host}}:9200/[매핑 확인할 인덱스 명]/_mapping

2.Document CRUD

CREATE

PUT

http://{{host}}:9200/[인덱스 명]/_create/[Document의 id값]

{
    "필드명1":"데이터값1",
    "필드명2":"데이터값2"
}

READ

GET

http://{{host}}:9200/[인덱스 명]/_doc/[read할 Document의 id]

CREATE 예시에서 아이디 값이 1인 doc을 생성했기 때문에 id 가 1인 doc을 read 했습니다.

UPDATE

POST

http://{{host}}:9200/[인덱스 명]/_update/[update할 document의 id]

{
    "doc":{
        "[update할 필드명]":"update할 필드값]"
    }
}

위의 update 요청 후에 read를 해보면 user1으로 등록했던 name값이 seaotter로 변경 되어있는것을 확인 할수 있습니다.

LIST

GET

http://{{host}}:9200/[인덱스 명]/_search

DELETE

http://{{host}}:9200/[인덱스 명]/_doc/[삭제할 document의 id]

LIST를 통해 얻은 Document의 id 값을 넣어서 요청을 보내면 doc이 삭제 됩니다.

LIST로 DELETE가 되었는지 확인해보면 아까 DELETE했던 아이디의 doc이 사라진것을 확인할수 있습니다.

Under the Sea Otter

Postman 사용법 / Elasticsearch CRUD및 인덱스 사용법