> 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 queries` 아래 예시에서)로 만들 수 있으며, 날짜 범위와 사용자 이름에 대한 변수를 포함합니다.

그런 다음 아래와 같은 새 쿼리를 만들어 템플릿 매크로(`user_activity_profile`)를 템플릿화된 검색(`user queries`)에서 가져오고, 사용자 이름과 날짜/시간 값을 전달하여 매크로를 호출할 수 있습니다. 그런 다음 *이* 검색(예를 들어 이름을 `run_user_activity_profile`로 지정)을 저장해 더 빠르게 접근할 수 있습니다.

```sql
-- pragma: template

--loads query user_activity_profile from the saved query 'user queries'
{% import 'user queries' user_activity_profile %}

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

## 템플릿화된 검색을 사용하는 방법

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

### 템플릿화된 검색 만들기

Panther Console의 Data Explorer에서 또는 로컬에서 CLI 워크플로를 통해 템플릿화된 검색을 만들 수 있습니다.

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

1. Panther 콘솔의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **조사** > **Data Explorer**.
2. SQL 편집기에서 `-- pragma: template` 를 맨 위에 추가하세요.
3. 다음을 사용하여 변수를 선언하는 SQL 쿼리를 만드세요 `{{}}` (이중 중괄호).
   * 예:

     ```sql
     -- pragma: template
     select {{p}}, {{q}}
     ```
4. 변수 값을 설정하려면 파일 상단에 다음과 같은 문장을 추가하세요:

   ```sql
   {% set <variable one name> = <variable one value> %}
   {% set <variable two name> = <variable two value> %}
   ```

   * 예:

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

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

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

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

SQL을 작성할 때 `Query` 키:

* 다음을 포함하세요 `-- pragma: template` 를 맨 위에 추가하세요.
* 변수를 이중 중괄호로 감싼 상태로 쿼리를 추가하세요.

예:

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

{% endtab %}
{% endtabs %}

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

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

1. Panther 콘솔의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **조사** > **Data Explorer**.
2. 오른쪽 상단에서 다음을 클릭합니다: **저장된 쿼리 열기**.
3. 실행하려는 템플릿화된 검색을 선택한 다음 클릭하세요 **쿼리 열기**.
4. SQL 표현식의 모든 변수가 파일 상단의 다음과 같은 문장에 값이 정의되어 있는지 확인하세요:

   ```sql
   {% set <variable one name> = <variable one value> %}
   {% set <variable two name> = <variable two value> %}
   ```
5. 다음을 클릭합니다: **쿼리 실행**.

**예시**

아래 예시에서 `p` 그리고 `q` 변수에는 다음 값이 할당됩니다 `1` 그리고 `'queue'`를 각각 클릭합니다.

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

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

## 템플릿 매크로를 사용하는 방법

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

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

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

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

1. Panther 콘솔의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **조사** > **Data Explorer**.
2. SQL 편집기에서 `-- pragma: template` 를 맨 위에 추가하세요.
3. 다음을 사용하여 변수를 선언하는 하나 이상의 SQL 쿼리를 만드세요 `{{}}` (이중 중괄호).
4. 각 템플릿화된 쿼리를 다음으로 감싸세요:
   * 쿼리 앞에: `{% macro <macro name>(<variable_one>, <variable_two>) export %}`
   * 쿼리 뒤에: `{% endmacro %}`
5. 다음을 클릭합니다: **다음 이름으로 저장,** 그리고 다음 필드의 값을 입력하세요:
   * **쿼리 이름**: 설명이 포함된 이름을 추가하세요.
     * 이 값은 나중에 가져올 때 사용됩니다.
   * **Tags**: 유사한 쿼리를 함께 그룹화하는 데 도움이 되도록 태그를 추가하세요.
   * **설명**: 쿼리의 목적을 설명하세요.
   * **기본 데이터베이스**: 쿼리를 수행할 데이터베이스를 선택하세요.
   * **이것은 예약 쿼리입니까?**: 이것을 켠 상태로 두세요 `끔`.
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).

SQL을 작성할 때 `Query` 키:

* 다음을 포함하세요 `-- pragma: template`를 맨 위에 추가하세요.
* 변수를 이중 중괄호로 감싼 상태로 하나 이상의 쿼리를 추가하세요.
* 각 템플릿화된 쿼리를 다음으로 감싸세요:
  * 쿼리 앞에: `{% macro <macro name>(<variable_one>, <variable_two>) export %}`
  * 쿼리 뒤에: `{% endmacro %}`

예:

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

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

{% endtab %}
{% endtabs %}

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

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

1. Panther 콘솔의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **조사** > **Data Explorer**.
2. SQL 편집기에서 다음을 추가하세요 `-- pragma: template` 를 맨 위에.

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

3. 다음과 같은 구조의 문장을 사용하여 이전에 정의한 매크로를 가져오세요:

   ```sql
   {% import '<name of Saved Search>' <name of macro> %}
   ```
4. 다음과 같은 구조의 문장을 사용하여 매크로를 호출하고, 인수 값들을 전달하세요:

   ```sql
   {{<name of macro>('<value of variable one>', '<value of variable two>')}}
   ```
5. 다음을 클릭합니다: **쿼리 실행**.
   * 원하면 다음을 클릭하여 쿼리를 저장할 수 있습니다 **다음 이름으로 저장**.

#### 전체 예시

```sql
-- pragma: template

--loads my_query1 from the Saved Search 'example macros'
{% import 'example macros' 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` 이 기능을 제공하는 함수입니다. 이는 다음을 사용할 때 유용할 수 있습니다 `다음과 같은` 루프.

예를 들어, 테이블 간에 쉽게 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.