> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/search/scheduled-searches/templated-searches.md).

# 템플릿 검색

## 개요

템플릿 검색은 [저장된 검색](/ko/search/scheduled-searches.md) (SQL로 작성되며) 변수를 포함합니다. 템플릿 매크로는 다른 저장된 검색으로 가져올 수 있고, 인수와 함께 호출할 수 있는 템플릿 검색입니다(함수 호출과 유사함).

템플릿 매크로로 정의하지 않고도 템플릿 검색을 저장할 수 있습니다. 이 경우 쿼리는 다른 곳에서 실행할 수 없으며, 변수 값은 동일한 저장된 검색에 제공됩니다.

자주 실행되는 SQL 표현식은 하나의 라이브러리 같은 저장된 검색에서 템플릿 매크로로 저장할 수 있어, 복잡한 SQL 코드를 더 쉽게 관리하고 재사용할 수 있습니다. 예를 들어 아래 영역과 관련된 쿼리의 "라이브러리"를 정의할 수 있습니다:

* 직원 매크로
* 상관 매크로
* 보강 매크로

Panther에서 템플릿 검색은 다음을 포함하여 정의합니다 `-- pragma: template` 를 SQL의 첫 줄로 사용합니다.

{% hint style="info" %}
Panther는 [Django 템플릿 언어](https://django.readthedocs.io/en/1.7.x/topics/templates.html)를 사용하며, 이는 [Jinja 템플릿](https://jinja.palletsprojects.com/en/3.1.x/)과 매우 유사합니다. 이는 대부분 [DBT](https://www.getdbt.com/) 템플릿이 상호 호환됨을 의미합니다.

Panther의 템플릿 엔진은 [pongo2](https://github.com/flosch/pongo2?tab=readme-ov-file)를 기반으로 하므로, 모든 Django 구문이 지원되는 것은 아닙니다. 다음을 참조하세요: [pongo2에 대해 나열된 주의 사항](https://github.com/flosch/pongo2?tab=readme-ov-file#caveats) 자세한 정보를 보려면.
{% endhint %}

### 사용 사례 예시

템플릿 매크로의 유용성을 보여주기 위해, 날짜 범위와 사용자 이름이 필요한 복잡한 쿼리(SQL 50줄 정도)를 가지고 있다고 가정해 보겠습니다. 템플릿 매크로가 없으면 이 검색을 실행할 때마다 특정 날짜 범위와 사용자 이름을 입력하도록 편집해야 하므로 번거롭고 오류가 발생하기 쉽습니다.

대신 이 복잡한 쿼리는 템플릿 매크로로 만들 수 있으며(이름은 `user_activity_profile` 아래 예시의 템플릿 검색(이름은 `사용자 쿼리` 이며, 날짜 범위와 사용자 이름에 대한 변수를 포함합니다.

그런 다음 아래와 같은 새 쿼리를 만들 수 있습니다. 이 쿼리는 템플릿 매크로(`user_activity_profile`)를 템플릿 검색(`사용자 쿼리`)에서 가져오고, 사용자 이름과 날짜 시간 값을 전달하여 매크로를 호출합니다. 그런 다음 *이* 검색을 저장할 수 있으며(예를 들어 `run_user_activity_profile`라고 부를 수 있음), 더 빠르게 액세스할 수 있습니다.

```sql
-- pragma: template

-- 저장된 검색 '사용자 쿼리'에서 query user_activity_profile를 불러옵니다
{% import '사용자 쿼리' user_activity_profile %}

{{user_activity_profile('bob_smith', '2023-01-01 00:00:00', '2023-01-02 00:00:00')}}
```

## 템플릿 검색 사용 방법

매크로로 정의하지 않고도 변수를 사용하는 템플릿 검색을 만들 수 있습니다. 이 경우 쿼리를 다른 저장된 검색으로 가져올 수는 없지만, 모든 변수 값이 파일 맨 위에 정의되어 있으므로 앞으로의 쿼리 실행은 더 간단해집니다.

### 템플릿 검색 만들기

Panther 콘솔의 Data Explorer에서 또는 로컬의 CLI 워크플로에서 템플릿 검색을 만들 수 있습니다.

{% tabs %}
{% tab title="콘솔" %}
**Panther 콘솔에서 템플릿 검색을 만드는 방법**

1. Panther Console의 왼쪽 탐색 모음에서 **검색**, 그런 다음 다음을 선택합니다 **데이터 탐색기** 탭.
2. SQL 편집기에서 다음을 추가합니다 `-- pragma: template` 를 맨 위에.
3. 다음을 사용하여 변수를 선언하는 SQL 쿼리를 만듭니다 `{{}}` (중괄호 두 개).
   * 예:

     ```sql
     -- pragma: template
     select {{p}}, {{q}}
     ```
4. 변수 값을 설정하려면 파일 맨 위에 다음과 같은 문을 추가합니다:

   ```sql
   {% set <변수 1 이름> = <변수 1 값> %}
   {% set <변수 2 이름> = <변수 2 값> %}
   ```

   * 예:

     ```sql
     -- pragma: template
     {% set p = "1" %}
     {% set q = "'queue'" %}

     select {{p}}, {{q}}
     ```
5. 클릭합니다 **다른 이름으로 저장** 그런 다음 다음 필드에 값을 입력합니다:
   * **쿼리 이름**: 설명적인 이름을 추가하세요.
   * **태그**: 유사한 쿼리를 함께 그룹화하는 데 도움이 되도록 태그를 추가합니다.
   * **설명**: 쿼리의 목적을 설명합니다.
   * **기본 데이터베이스**: 쿼리를 실행할 데이터베이스를 선택합니다.
   * **이 쿼리는 예약된 쿼리입니까?**: 이 설정을 전환합니다 `켜기` 이 쿼리를 지정된 간격으로 실행하려는 경우.
     * 이 설정을 전환하면 `켜기`, 시간 간격을 지정하세요.
6. 클릭합니다 **쿼리 저장**.
   {% endtab %}

{% tab title="CLI" %}
**CLI 워크플로에서 템플릿 검색을 만드는 방법**

CLI 워크플로에서 템플릿 검색을 만들려면 다음을 따르세요: [CLI 워크플로에서 저장된 검색을 만드는 방법 안내](/ko/search/scheduled-searches.md#how-to-create-a-saved-search-in-the-cli-workflow).

CLI의 SQL을 작성할 때 `Query` 키:

* 포함 `-- pragma: template` 를 맨 위에.
* 변수를 이중 중괄호로 감싼 쿼리를 추가합니다.

예:

```yaml
Query: |-
    -- pragma: template
    {% set p = "1" %}
    {% set q = "'queue'" %}
    select '{{p}}', '{{q}}'
```

{% endtab %}
{% endtabs %}

### Data Explorer에서 템플릿 검색 실행하기

이전에 정의한 템플릿 검색을 열고 변수 값을 제공하여 Data Explorer에서 실행할 수 있습니다.

1. Panther Console의 왼쪽 탐색 모음에서 **검색**, 그런 다음 다음을 선택합니다 **데이터 탐색기** 탭.
2. 오른쪽 상단에서 다음을 클릭하세요: **저장된 쿼리 열기**.
3. 실행하려는 템플릿 검색을 선택한 다음 **쿼리 열기**.
4. SQL 표현식의 모든 변수가 파일 상단의 다음과 같은 문에서 값으로 정의되어 있는지 확인합니다:

   ```sql
   {% set <변수 1 이름> = <변수 1 값> %}
   {% set <변수 2 이름> = <변수 2 값> %}
   ```
5. 클릭합니다 **쿼리 실행**.

**예시**

아래 예시에서 `p` 및 `q` 변수에는 다음 값이 지정됩니다 `1` 및 `'queue'`를 각각 사용합니다.

```sql
-- pragma: template
{% set p = "1" %}
{% set q = "'queue'" %}

select {{p}}, {{q}}
```

## 템플릿 매크로 사용 방법

템플릿 매크로는 내보내기된 하나 이상의 템플릿 검색으로, 다른 검색에서 가져올 수 있습니다. 여러 매크로를 하나의 템플릿 쿼리로 묶어 사실상 관련 매크로의 "라이브러리"를 만드는 것이 특히 유용할 수 있습니다.

### 템플릿 매크로 만들기

Panther 콘솔의 Data Explorer에서 또는 로컬의 CLI 워크플로에서 템플릿 매크로를 만들 수 있습니다.

{% tabs %}
{% tab title="콘솔" %}
**Panther 콘솔에서 템플릿 매크로를 만드는 방법**

1. Panther Console의 왼쪽 탐색 모음에서 **검색**, 그런 다음 다음을 선택합니다 **데이터 탐색기** 탭.
2. SQL 편집기에서 다음을 추가합니다 `-- pragma: template` 를 맨 위에.
3. 다음을 사용하여 변수를 선언하는 하나 이상의 SQL 쿼리를 만듭니다 `{{}}` (중괄호 두 개).
4. 각 템플릿 쿼리를 다음으로 감쌉니다:
   * 쿼리 앞에: `{% macro <매크로 이름>(<변수 1>, <변수 2>) export %}`
   * 쿼리 뒤에: `{% endmacro %}`
5. 클릭합니다 **다른 이름으로 저장** 그런 다음 다음 필드에 값을 입력합니다:
   * **쿼리 이름**: 설명적인 이름을 추가하세요.
     * 이 값은 나중에 가져올 때 사용됩니다.
   * **태그**: 유사한 쿼리를 함께 그룹화하는 데 도움이 되도록 태그를 추가합니다.
   * **설명**: 쿼리의 목적을 설명합니다.
   * **기본 데이터베이스**: 쿼리를 실행할 데이터베이스를 선택합니다.
   * **이 쿼리는 예약된 쿼리입니까?**: 이 상태를 켜둔 채로 두세요 `끔`.
6. 클릭합니다 **쿼리 저장**.

**예시**

```sql
-- pragma: template
{% macro my_query1(p, q) export %}
select '{{p}}', '{{q}}'
{% endmacro %}

{% macro my_query2(x) export %}
select {{x}}}
{% endmacro %}
```

{% endtab %}

{% tab title="CLI" %}
**CLI 워크플로에서 템플릿 매크로를 만드는 방법**

CLI 워크플로에서 템플릿 검색을 만들려면 다음을 따르세요: [CLI 워크플로에서 저장된 검색을 만드는 방법 안내](/ko/search/scheduled-searches.md#how-to-create-a-saved-search-in-the-cli-workflow).

CLI의 SQL을 작성할 때 `Query` 키:

* 포함 `-- pragma: template`를 맨 위에.
* 변수를 이중 중괄호로 감싼 하나 이상의 쿼리를 추가합니다.
* 각 템플릿 쿼리를 다음으로 감쌉니다:
  * 쿼리 앞에: `{% macro <매크로 이름>(<변수 1>, <변수 2>) export %}`
  * 쿼리 뒤에: `{% endmacro %}`

예:

```yaml
Query: |-
    -- pragma: template
    {% macro my_query1(p, q) export %}
    select '{{p}}', '{{q}}'
    {% endmacro %}

    {% macro my_query2(x) export %}
    select {{x}}}
    {% endmacro %}
```

{% endtab %}
{% endtabs %}

### 다른 쿼리에서 템플릿 매크로 호출하기

이전에 만든 템플릿 매크로를 가져와 변수 값을 전달하여 실행할 수 있습니다.

1. Panther Console의 왼쪽 탐색 모음에서 **검색**, 그런 다음 다음을 선택합니다 **데이터 탐색기** 탭.
2. SQL 편집기에서 다음을 추가합니다 `-- pragma: template` 를 맨 위에.

{% hint style="info" %}
확장된 SQL을 표시하고 싶다면(예: 디버깅에 도움이 되도록) 다음을 포함합니다 `-- pragma: show macro expanded`.
{% endhint %}

3. 다음과 같은 형식의 문으로 이전에 정의한 매크로를 가져옵니다:

   ```sql
   {% import '<저장된 검색 이름>' <매크로 이름> %}
   ```
4. 다음과 같은 형식의 문으로 매크로를 호출하고 인수에 값을 전달합니다:

   ```sql
   {{<매크로 이름>('<변수 1의 값>', '<변수 2의 값>')}}
   ```
5. 클릭합니다 **쿼리 실행**.
   * 원하면 다음을 클릭하여 쿼리를 저장합니다 **다른 이름으로 저장**.

#### 전체 예시

```sql
-- pragma: template

-- 저장된 검색 '예시 매크로'에서 my_query1를 불러옵니다
{% import '예시 매크로' my_query1 %}

{{my_query1('1.1.1.1', 'test')}}
```

### 템플릿 매크로 디버깅

Data Explorer에서 템플릿 매크로를 실행할 때 다음을 추가하여 확장된 SQL 문을 볼 수 있습니다(템플릿 코드만이 아니라): `-- pragma: show macro expanded` 아래의 `-- pragma: template` 문을 추가하면 됩니다.\
\
예를 들어, Data Explorer에서 아래를 실행하면:

```sql
-- pragma: template
-- pragma: show macro expanded
{% set p = "1" %}
{% set q = "'queue'" %}

select {{p}}, {{q}}
```

템플릿은 확장된 SQL로 대체됩니다:

```sql
-- pragma: template
-- pragma: show macro expanded

select 1, 'queue'
```

### 사용자 정의 함수

Panther는 템플릿 작성을 더 쉽게 하기 위해 사용자 정의 함수를 구현했습니다.

#### `split`

Django는 문자열을 목록으로 분할하는 기능을 지원하지 않습니다. Panther는 다음을 추가했습니다: `split` 이 기능을 제공하는 함수입니다. 이는 다음과 함께 작업할 때 유용할 수 있습니다: `for` 루프.

예를 들어, 여러 테이블을 쉽게 UNION하는 다음 쿼리를 살펴보세요:

```jinja
{% for table_name in split("aws_cloudtrail,panther_audit", ",") %}
    {% if not forloop.First %} union {% endif %}
    select
        '{{ table_name | upper }}' as p_table_name,
        p_event_time,
        p_log_type,
        p_any_ip_addresses,
        p_row_id,
    from panther_logs.public.{{table_name}}
    where p_occurs_since(1d)
        and ARRAY_CONTAINS('142.161.78.139'::variant, p_any_ip_addresses)
{% endfor %}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.panther.com/ko/search/scheduled-searches/templated-searches.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.