Infragraph 쿼리 언어 레퍼런스

쿼리 언어를 사용하면 그래프를 탐색하고, 속성으로 노드를 필터링하며, 리소스 사이의 엣지(edge)를 따라 이동할 수 있어요.

출처: 문서

본문

예시 쿼리 모음은 Example queries를 참고하세요.

쿼리 모델

Infragraph 쿼리는 최상위 query 객체를 가진 JSON 본문이에요. 이 객체는 node와 edge 블록이 번갈아 중첩된 시퀀스로 구성되며, 그래프를 통과하는 탐색 경로(traversal path)를 정의해요. 최상위 node 객체는 탐색의 시작 노드를 정의하고, 최상위 edge 블록은 정의된 관계와 일치하는 노드를 찾아요. 각 edge 블록은 nodeQuery 블록을 포함하며, 여기서 다음 node와 edge 블록을 계속 이어 붙여 그래프를 탐색할 수 있어요.

Infragraph는 최대 20개 노드의 탐색 깊이를 지원해요.

다음 목록은 query의 명세를 정의해요.

node: map | 필수unifiedTypes: list [string] | sourceTypes가 정의되지 않은 경우 필수sourceTypes: list [string] | unifiedTypes가 정의되지 않은 경우 필수ids: list [string] | 선택alias: string | 선택where: list [match 및 filterGroup 객체] | 선택match map | [filterGroup]이 정의되지 않은 경우 필수left: map | 필수property: map | 필수name: string | 필수alias: string | 선택comparator: string | 필수right: map | 필수value: map | valueList가 정의되지 않은 경우 필수valueList map | value가 정의되지 않은 경우 필수values list [value] | 필수filterGroup map | match가 정의되지 않은 경우 필수operator string | 필수filter: list [match] | 필수
edge: map | 필수edgeTypes: list [string] | 필수direction: string | 필수absent: boolean | 선택nodeQuery: map | 필수node: map | 필수edge: map | 선택

전체 모델

다음 쿼리는 지원되는 모든 인자를 포함해요.

{
  "node": {
    "sourceTypes": [ "<VALUE>" ],
    "alias": "<VALUE>",
    "where": [
      {
        "filterGroup": {
          "operator": "<OPERATOR>",
          "filter": [
            {
              "match": {
                "left": { "property": { "name": "<VALUE>" } },
                "comparator": "<COMPARATOR>",
                "right": { "valueList": { "values": [
                  { "string": "<VALUE>" },
                  { "string": "<VALUE>" }
                ]}}
              }
            },
            {
              "match": {
                "left": { "property": { "name": "<VALUE>" } },
                "comparator": "<COMPARATOR>",
                "right": { "value": { "string": "<VALUE>" } }
              }
            }
          ]
        }
      }
    ]
  },
  "edge": {
    "direction": "<DIRECTION>",
    "nodeQuery": {
      "node": {
        "unifiedTypes": [ "<VALUE>" ],
        "ids": ["<VALUE>", "<VALUE>"],
        "alias": "<VALUE>",
        "where": [
          {
            "match": {
              "left": { "property": { "alias": "<REFERENCE.TO.ALIAS>", "name": "<VALUE>" } },
              "comparator": "EQUAL",
              "right": { "property": { "alias": "<REFERENCE.TO.ALIAS>", "name": "<VALUE>" } }
            }
          }
        ]
      }
    },
    "edgeTypes": [ "<EDGE.TYPE>" ]
  }
}

명세

이 섹션은 JSON 기반 Infragraph 쿼리를 만드는 데 사용되는 필드에 대한 자세한 내용을 제공해요.

node

node 블록은 탐색의 현재 단계에서 일치시킬 노드를 정의해요. unifiedTypes 또는 sourceTypes 중 하나 이상을 지정해야 하며, 선택적으로 특정 ids 필터를 제공할 수 있어요.

기본값: 없음
필수 필드예요.
데이터 타입: unifiedTypes 또는 sourceTypes 중 하나 이상을 포함하는 객체. 둘 다 정의할 수 있어요.unifiedTypes: 공급자 전반의 일반화된 추상 유형을 기준으로 노드를 일치시켜요. 쿼리당 하나의 "*" 와일드카드를 지원해 어떤 노드 유형과도 일치할 수 있어요.sourceTypes: 공급자별 정확한 유형을 기준으로 노드를 일치시켜요. 와일드카드를 지원하지 않아요.ids: 특정 그래프 노드 ID와 일치시켜요. 와일드카드를 지원하지 않아요.where: 일치된 노드에 적용할 속성 필터 목록이에요.

이러한 차원은 논리 AND로 결합돼요. 예를 들어 unifiedTypes=["VIRTUAL_MACHINE"]와 sourceTypes=["AWS_EC2_INSTANCE"]를 모두 제공하면 두 제약을 모두 충족하는 노드를 찾아요.

다음은 node 블록의 예시예요.

{
  "node": {
    "unifiedTypes": ["VIRTUAL_MACHINE"],
    "where": [
      {
        "match": {
          "left": { "property": { "name": "status" } },
          "comparator": "EQUAL",
          "right": { "value": { "string": "running" } }
        }
      }
    ]
  }
}

unifiedTypes

공급자 전반의 일반화된 추상 유형(예: ["VIRTUAL_MACHINE"])을 기준으로 노드를 일치시켜요. 쿼리당 하나의 "*" 와일드카드를 지원해 어떤 노드 유형과도 일치할 수 있어요.

기본값: 없음
sourceTypes를 정의하지 않으면 필수예요. 둘 다 정의할 수 있어요.
데이터 타입: 문자열 목록
최대 5개 요소를 지원해요.

sourceTypes

공급자별 정확한 유형(예: ["AWS_EC2_INSTANCE"])을 기준으로 노드를 일치시켜요. 와일드카드를 지원하지 않아요.

기본값: 없음
unifiedTypes를 정의하지 않으면 필수예요. 둘 다 정의할 수 있어요.
데이터 타입: 문자열 목록
최대 5개 요소를 지원해요.

ids

특정 그래프 노드 ID와 일치시켜요. 와일드카드를 지원하지 않아요.

기본값: 없음
데이터 타입: 문자열 목록
최대 10개 요소를 지원해요.

alias

이 노드에 할당할 선택적 참조 별칭이에요. where 절의 left 또는 right 블록에서 이 별칭을 참조해, 현재 노드의 속성과 탐색에서 더 일찍 나타난 별칭 노드의 속성 간 비교를 수행할 수 있어요.

기본값: 없음
데이터 타입: string

where

일치된 노드에 적용할 속성 필터 목록이에요. Infragraph는 where 블록의 최상위 항목을 논리 AND 연산자로 일치시켜요. filterGroup을 사용해 OR 연산자로 여러 필터를 일치시킬 수 있어요.

여러 filterGroup 블록을 결합해 AND와 OR 연산자의 조합을 만들 수 있어요. 예를 들어 (A OR B) AND (C OR D) 논리를 일치시키려면 하나의 filterGroup으로 A 또는 B 필터 하나 이상을 일치시키고, C 또는 D 필터 중 하나와도 일치해야 해요.

기본값: 없음
데이터 타입: match 및 filterGroup 객체 목록
최대 10개 요소를 지원해요.

match

모든 match 절 또는 filterGroup 절을 충족하는 node 객체를 찾아요.

기본값: 없음
데이터 타입: mapleft: 검사할 속성이에요.comparator: 수행할 연산이에요.right: left 값과 비교할 값이에요.

다음은 IN 비교자를 사용한 match 절 예시예요.

{
  "match": {
    "left": { "property": { "name": "region" } },
    "comparator": "IN",
    "right": {
      "valueList": {
        "values": [
          { "string": "us-east-1" },
          { "string": "us-west-2" }
        ]
      }
    }
  }
}

left

match 절에서 검사할 속성이에요.

기본값: 없음
데이터 타입: 하나의 property 객체

property

각 property 객체는 다음 필드를 포함해요.

필드	설명	필수 여부
`name`	`right` 필드에 정의된 값과 비교할 속성 이름	예
`alias`	탐색의 다른 곳에 있는 노드를 식별해서, 현재 노드가 아닌 해당 노드의 속성과 비교하도록 함	아니요

노드를 별칭으로 참조하려면 match 절의 left와 right 속성이 모두 노드를 별칭으로 참조해야 해요. 다음은 별칭으로 노드를 참조하는 match 절의 예시예요.

"match": {
  "left": { "property": { "alias": "vm", "name": "tags.Environment" } },
  "comparator": "EQUAL",
  "right": { "property": { "alias": "group", "name": "tags.Environment" } }
}

comparator

match 절의 left와 right 필드 값을 비교하기 위해 수행할 연산이에요.

기본값: 없음
데이터 타입: string

지원되는 비교자에 대한 자세한 내용은 Comparators를 참고하세요.

right

left 값과 비교할 값이에요.

기본값: 없음
데이터 타입: property, value, valueList 중 하나

property 필드에 대한 정보는 property를 참고하세요.

value는 정확히 하나의 데이터 타입과 하나의 값을 포함하는 객체예요. 다음은 value 객체 예시 목록이에요.

"right": { "value": { "string": "us-east-1" } }
"right": { "value": { "int": 42 } }
"right": { "value": { "float": 1.5 } }
"right": { "value": { "bool": true } }
"right": { "value": { "timestamp": "2025-02-07T23:00:00-01:00" } }

valueList는 value 객체의 목록이에요. Infragraph는 comparator를 IN 또는 NOT_IN으로 설정한 경우에만 valueList 객체를 지원해요. 이 블록은 최대 10개 요소를 지원하며, 모든 요소는 같은 타입이어야 해요.

다음은 valueList를 제공하는 right 객체 예시예요.

"right": {
  "valueList": {
    "values": [
      { "string": "us-east-1" },
      { "string": "us-west-2" }
    ]
  }
}

탐색 결과를 다듬는 데 사용하는 하나의 operator와 하나 이상의 filter를 정의해요.

기본값: 없음
데이터 타입: 하나의 operator와 하나의 filter를 포함하는 객체.필수 operator 하나. AND 또는 OR 값이어야 하는 문자열.필수 filter 하나. match 블록 목록이어야 함.
최대 10개의 filter 블록을 지원해요.

다음 예시는 두 필터가 있는 filterGroup을 정의해요. operator가 OR로 설정되어 있으므로 이 필터 그룹은 두 필터 중 하나와 일치하는 노드를 반환해요.

{
  "filterGroup": {
    "operator": "OR",
    "filter": [
      {
        "match": {
          "left": { "property": { "name": "environment" } },
          "comparator": "EQUAL",
          "right": { "value": { "string": "production" } }
        }
      },
      {
        "match": {
          "left": { "property": { "name": "is_critical" } },
          "comparator": "EQUAL",
          "right": { "value": { "bool": true } }
        }
      }
    ]
  }
}

edge

edge 블록은 현재 일치된 노드에서 다음 노드 집합으로 어떻게 탐색할지 결정해요.

기본값: 없음
데이터 타입: Object필수 edgeTypes 하나. 쿼리당 어떤 엣지 유형에도 * 와일드카드 하나를 지원해요.필수 direction 하나.선택 absent 하나.필수 nodeQuery 하나.

다음은 edge 블록의 예시예요.

{
  "edge": {
    "edgeTypes": ["ATTACHES_TO"],
    "direction": "OUTGOING",
    "nodeQuery": {
      "node": {
        "unifiedTypes": ["ROLE"]
      }
    }
  }
}

edgeTypes

탐색할 관계(예: ["MANAGES", "CONTAINS"])예요. 쿼리당 어떤 엣지 유형에도 * 와일드카드 하나를 지원해요.

기본값: 없음
필수 필드예요.
데이터 타입: 문자열 목록
최대 5개 요소를 지원해요.

Infragraph는 다음 엣지 유형을 지원해요.

direction

탐색할 관계의 방향이에요.

기본값: OUTGOING
필수 필드예요.

이 필드의 유효한 값 목록은 다음과 같아요.

absent

true로 설정하면 쿼리가 NOT 단계처럼 동작해서, 지정된 엣지가 없는 노드를 일치시켜요.

기본값: 없음
데이터 타입: boolean

nodeQuery

탐색의 중첩된 다음 단계로, 다른 node와 선택적 edge를 포함해요.

기본값: 없음
데이터 타입: 하나의 node 객체를 포함하는 객체.

비교자 (Comparators)

Infragraph는 다음 비교자를 지원해요.

비교자	오른쪽 피연산자	허용되는 값 유형	비고
`EQUAL`	`value` 또는 `property`	`string`, `int`, `float`, `bool`, `timestamp`	완전 일치.
`NOT_EQUAL`	`value` 또는 `property`	`string`, `int`, `float`, `bool`, `timestamp`	`EQUAL`의 반대.
`GREATER_THAN`	`value` 또는 `property`	`string`, `int`, `float`, `bool`, `timestamp`	순서 비교.
`LESS_THAN`	`value` 또는 `property`	`string`, `int`, `float`, `bool`, `timestamp`	순서 비교.
`GREATER_THAN_OR_EQUAL`	`value` 또는 `property`	`string`, `int`, `float`, `bool`, `timestamp`	순서 비교.
`LESS_THAN_OR_EQUAL`	`value` 또는 `property`	`string`, `int`, `float`, `bool`, `timestamp`	순서 비교.
`EXISTS`	없음	없음	오른쪽 피연산자를 완전히 생략해야 함.
`DOES_NOT_EXIST`	없음	없음	오른쪽 피연산자를 완전히 생략해야 함.
`IS_NOT_EMPTY`	없음	없음	오른쪽 피연산자를 완전히 생략해야 함.
`IN`	`valueList` (필수)	`string`, `int`, `float` (동종 목록)	`bool`과 `timestamp` 값은 `valueList` 안에서 거부됨.
`NOT_IN`	`valueList` (필수)	`string`, `int`, `float` (동종 목록)	`IN`과 동일한 제한.
`STARTS_WITH`	`value` (필수)	`string`만, 비어있지 않아야 함	오른쪽 값은 비어있지 않은 `string`(≤ 1024자)이어야 하며, 다른 유형/형태는 거부됨.

제한 사항

Query API는 쿼리에 대해 다음 구조적 제한을 적용해요. 이 제한을 초과하면 Infragraph는 상세한 필드 위반을 포함한 400 Bad Request 응답을 반환해요.

탐색 깊이: 최대 20개의 중첩 node/edge 쌍.
노드 필터:unifiedTypes: 최대 5개 요소.sourceTypes: 최대 5개 요소.ids: 최대 10개 요소.전체 쿼리에서 모든 노드 유형에 와일드카드(*)는 1개만 허용됨.
엣지 필터:edgeTypes: 최대 5개 요소.전체 쿼리에서 모든 엣지 유형에 와일드카드(*)는 1개만 허용됨.
술어 (where 절):단일 where 목록에 최대 10개 항목.단일 filterGroup 안에 최대 10개 항목.최대 술어 중첩 깊이 10.
값:필터의 문자열 값은 1024자를 초과할 수 없음.valueList (IN/NOT_IN용)은 최대 10개 값으로 제한되며, 모든 값은 정확히 같은 유형이어야 함.
속성 마스크:node_properties 문자열은 2048자를 초과할 수 없음.

더 알아보기 (Learn more)

Infragraph 예시 쿼리 — 실용적인 JSON 쿼리 예시를 확인해 봐요.
Infragraph 쿼리 — 쿼리 구성 요소와 실행 방법을 알아봐요.
그래프 탐색기 — 쿼리를 빌드하고 실행하는 방법을 알아봐요.