Weegloo Docs - 공통 쿼리 파라미터

WEEGLOO의 목록 조회 엔드포인트(GET /spaces/{spaceId}/contents처럼 컬렉션을 돌려주는 GET)는 공통 쿼리 파라미터를 받습니다. 이 파라미터로 한 페이지에 가져올 개수를 제한하고, 정렬 기준을 정하고, 연관 리소스를 함께 가져오고, 필요한 필드만 골라 받고, 조건으로 목록을 좁히고, 다음·이전 페이지로 이동합니다.

이 파라미터들은 리소스 종류와 상관없이 같은 방식으로 동작합니다. 개별 리소스 레퍼런스는 그 리소스 고유의 조건만 따로 설명하고, 여기서 다루는 공통 파라미터는 이 페이지를 참조합니다.

파라미터

파라미터	타입	설명
`limit`	integer	한 페이지에 반환할 항목 수. 1~100. 기본값 15.
`skip`	integer	건너뛸 항목 수. 기본값 0. 페이지 이동에는 `skip` 대신 커서(`next`·`prev`)를 씁니다. 아래 페이지네이션 (커서)를 참조하세요.
`next`	string	다음 페이지 커서. 이전 응답의 `links.next`에서 얻습니다.
`prev`	string	이전 페이지 커서. 이전 응답의 `links.prev`에서 얻습니다.
`order`	string	정렬 기준. 쉼표로 여러 기준을 이어 다중 정렬합니다(예: `sys.createdAt,sys.id`). 기본값 `sys.createdAt,sys.id`. `fields.`로 시작하는 필드는 로케일을 포함합니다(예: `fields.title.en-US`).
`include`	integer	연관 리소스를 함께 펼쳐 가져올 수준. 0=기본, 1=연관 리소스, 2=중첩 관계, 3=전체. 기본값 0.
`select`	string	결과에 포함할 필드(예: `sys.id,sys.createdAt`) 또는 제외할 필드(예: `-sys.id`)를 쉼표로 나열합니다. 포함과 제외를 한 요청에서 섞지 않습니다.
`filter`	(조건)	조건으로 목록을 좁힙니다. 형식은 아래 필터를 참조하세요.

order·select에 쓰는 sys 필드의 종류는 시스템 속성 (sys)에서 확인할 수 있습니다.

필터

필터 조건은 filter[]로 감싸지 않고 쿼리 파라미터로 직접 보냅니다. 형식은 {필드}[{연산자}]={값}이며, 연산자를 생략하면 eq로 해석합니다. 쓸 수 있는 연산자 전체는 아래 연산자를 참조하세요.

{필드}[{연산자}]={값}

예를 들어 name이 텀블러로 시작하는 항목만 가져오려면 name[prefix]=텀블러로 보냅니다. 규칙과 주의사항은 다음과 같습니다.

filter[]로 감싸지 않습니다. filter[name[prefix]]=텀블러처럼 감싸면 동작하지 않습니다.
여러 조건은 AND로 묶입니다. 모두 만족하는 항목만 남고, 하나만 만족하면 되는 OR 검색은 지원하지 않습니다. 한 필드에서 여러 값 중 하나를 맞히려면 in을 씁니다.
fields. 조건은 로케일을 포함합니다. 예를 들어 fields.file.ko-KR.mimeGroups=Image는 Media 목록에서 이미지 파일만, sys.createdAt[gte]=2026-06-01T00:00:00Z는 그 시점 이후 생성된 항목만 가져옵니다.
fields.로 Content 목록을 필터·정렬할 때는 Content Type도 지정해야 합니다. sys.contentType.sys.id를 함께 보내야 하며(/contents 목록 한정), contentType=만으로는 대신할 수 없습니다. 자세한 내용은 Content 레퍼런스를 참조하세요.

연산자

연산자	의미	값
`eq`	같음. 연산자를 생략하면 이것으로 해석합니다.	단일 값
`ne`	다름	단일 값
`in`	나열한 값 중 하나와 같음	값 목록
`nin`	나열한 값 어느 것과도 다름	값 목록
`all`	배열 필드가 나열한 값을 모두 포함	값 목록
`exists`	값의 존재 여부	`true` 또는 `false`
`prefix`	접두 일치	단일 값
`gt` / `gte`	초과 / 이상	단일 값
`lt` / `lte`	미만 / 이하	단일 값
`regex`	정규식 일치. 고급 검색 전용(아래 고급 검색).	정규식
`near`	Location 필드가 한 지점에서 일정 거리 안. 고급 검색 전용.	`위도,경도,거리` (거리 단위 킬로미터)
`within`	Location 필드가 다각형 안. 고급 검색 전용.	`위도,경도` 좌표를 세 쌍 이상 이어 붙인 값

RichText·Json 필드는 검색 대상이 아니라 필터 조건에 쓸 수 없습니다.

고급 검색 (Advanced Search)

regex·near·within 연산자와 텍스트 전문검색은 고급 검색에서만 동작합니다. 고급 검색은 목록 조회 요청에 헤더 X-Weegloo-Advanced-Search: true를 더해 켜며, 응답에도 같은 헤더가 실려 옵니다.

전문검색: 전문검색이 켜진 텍스트 필드(LongText)에 eq를 쓰면, 정확히 같은 값이 아니라 그 값이 포함된 항목까지 부분·유사 매칭으로 찾습니다. 고급 검색을 켜지 않았거나 요금제가 고급 검색을 제공하지 않으면 같은 eq가 정확 일치로 동작합니다.
Location 검색: near(반경)·within(다각형)은 Location 필드에만 쓰며 고급 검색에서만 동작합니다.
고급 검색을 쓸 수 없는 요청에서 regex·near·within을 보내면 받아들여지지 않습니다.

페이지네이션 (커서)

목록 응답 본문에는 links 객체가 들어 있고, 그 안에 next·prev가 있습니다. links.next는 다음 페이지로 가는 전체 경로입니다.

/v1/spaces/HnQ32YiH/contents?limit=15&next=<커서>

다음 페이지를 가져오는 방법은 두 가지입니다. links.next 경로를 그대로 호출하거나, links.next에서 next 커서 값을 꺼내 다음 요청의 next 파라미터로 넘깁니다. links.next가 없으면 마지막 페이지입니다. 이전 페이지는 links.prev로 같은 방식으로 이동합니다.

페이지를 넘길 때 skip을 늘려 쓰지 마세요. 목록 사이에 항목이 추가·삭제되면 skip 위치가 어긋나 항목이 빠지거나 중복될 수 있습니다. 커서(next·prev)는 이런 문제가 없습니다.

다음은 목록 응답의 구조 예시입니다. 래퍼의 sys.type은 TotalPageResponse이고, items에 항목 배열이, links에 이동 경로가 들어갑니다.

{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/HnQ32YiH/contents?limit=15",
    "next": "/v1/spaces/HnQ32YiH/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}

totalCount는 조건에 맞는 전체 항목 수이고, limit은 이 응답에 적용된 한 페이지 크기입니다. items에는 그 페이지에 해당하는 항목만 담깁니다.

시스템 속성 (sys): order·select에 쓰는 sys 필드.
규약: 미디어 타입·JSON Patch·동시성.

파라미터

필터

연산자

고급 검색 (Advanced Search)

페이지네이션 (커서)

관련 문서