지난번에는 OCI Data Catalog의 기본으로서, Object Storage에 배치한 CSV와 Parquet를 하베스트 (Harvest, 수집)하여 Data Asset, Connection, 논리 Data Entity, Attribute, 증분 하베스트를 확인했습니다.

Oracle Database 매뉴얼은 26ai, 19c, 12.2 등 제품 버전별로 다수 존재합니다.

PDF를 Object Storage에 배치하면 파일을 일원 관리할 수 있지만, PDF 파일명과 저장 위치만으로는 다음과 같은 정보를 충분히 관리할 수 없습니다.

• 정식 문서명
• 제품명 및 제품 버전
• 문서 계열
• 문서 번호
• 문서 카테고리
• Oracle 공식 URL
• RAG에서 사용하는 문서인지 여부
• 향후 Database에서 JOIN할 때 사용할 문서 ID

이러한 정보를 관리하는 방법으로 Oracle 웹사이트를 분석하여 문서 목록을 자동 생성하는 방법도 생각할 수 있습니다.

하지만 웹 페이지의 구조 변경, 문서별 URL 차이, PDF 유무, 문서명 변경 등도 고려해야 하므로, OCI Data Catalog 학습으로서는 난이도가 높아집니다.

그래서 이번에는, 이미 Object Storage에 배치되어 있는 PDF 파일군을 대상으로 합니다.

문서 관리 정보는 사람이 확인하기 쉬운 CSV로 작성하고, Python으로 타입과 내용을 검증하여 Parquet로 변환합니다. 그 후, PDF와 문서 인벤토리 Parquet를 OCI Data Catalog에서 하베스트합니다.

나아가 OCI Data Catalog의 Custom Properties를 사용하여, PDF의 Data Entity에 제품 버전, 정식 문서명, 공식 URL 등의 업무 메타데이터를 추가합니다.

따라서, Object Storage 상의 Oracle Database 매뉴얼 PDF와 문서 인벤토리 Parquet를 OCI Data Catalog로 카탈로그화해 보겠습니다.

본 시리즈에서는 Object Storage에 저장한 데이터를 OCI Data Catalog로 발견·관리하고, Autonomous AI Database, AI Vector Search, Select AI로 단계적으로 연결합니다.

제2회에서 작성하는 document_id와 document_family_id는 제3회, 제4회에서도 사용할 수 있도록 합니다.

이번 목표는 다음 상태를 만드는 것입니다.

Oracle Database 매뉴얼 PDF
↓
OCI Object Storage에 배치
...

이번 검증에서는 다음 상태까지 확인할 수 있었습니다.

이번에 작성할 주요 파일은 다음과 같습니다.

먼저, PDF 본체와 문서 인벤토리의 역할, 대상 문서, Object Storage 배치, 관리 항목을 결정합니다.

PDF는 문서의 실체입니다.

documents/oracle-database/26ai/admin/database-administrators-guide.pdf

문서 인벤토리는 PDF를 설명하는 관리 정보입니다.

catalog/document_inventory/current/document_inventory.parquet

두 항목은 document_id와 object_name으로 매핑합니다.

OCI Data Catalog는 Parquet를 하베스트(Harvest)하면, 열 이름(column name)이나 데이터 타입(data type) 등의 **기술 메타데이터 (technical metadata)**를 Data Entity와 Attribute로 등록합니다.

document_inventory.parquet의 각 행이 자동으로 개별 PDF Data Entity로 변환되거나, PDF의 Custom Properties로 자동 전기되는 것은 아닙니다.

Parquet
→ 파일과 스키마(schema)를 카탈로그화
PDF
...

이번 CSV와 Parquet는 다음 용도로 사용합니다.

• 문서 관리 정보의 마스터
• Data Catalog에서 관리하는 문서 항목의 정의
• 제4회에서 Autonomous AI Database의 외부 표(External Table)로 참조
• Vector 표와 JOIN하기 위한 공통 키
• Autonomous AI Database나 다른 데이터 카탈로그로 전달할 공통 데이터

OCI Data Catalog가 Object Storage에서 스키마를 인식하는 주요 형식에는 CSV, XML, Avro, Excel, Parquet, ORC, JSON이 있습니다.

PDF는 지원 대상인 구조화된 파일 형식이 아니므로, 하베스트 작업(Harvest job)에서 Include Unrecognized Files를 활성화합니다.

PDF에서 가져오는 것은 주로 파일 이름이나 Object Storage 상의 경로와 같은 기본 정보입니다.

참고:

로컬 PC 또는 OCI Cloud Shell
├── data/
│   └── document_inventory.csv
...

이번에는 26ai, 19c, 12.2에서 공통적으로 존재하는 다음 3개 시리즈를 대상으로 합니다.

• Database Administrator's Guide
• Database Installation Guide for Linux
• Database Concepts

26ai에 대해서는 AI Vector Search User's Guide도 추가합니다.

document_family_id |
26ai | 19c | 12.2 |
|---|---|---|---|
database_administrator_guide |
○ | ○ | ○ |
database_installation_guide_linux |
○ | ○ | ○ |
database_concepts |
○ | ○ | ○ |
ai_vector_search_users_guide |
○ | － | － |

이번 샘플에서는 총 10개의 문서를 관리합니다.

문서 번호나 발행 연월은 Oracle의 문서 업데이트에 따라 변경될 수 있습니다. CSV 값은 Object Storage에 배치한 PDF의 표지 또는 Title and Copyright Information을 확인하여 설정해 주세요.

Oracle Database Books 페이지:

Object Storage에서는 제품, 버전, 문서 계열을 경로(path)를 통해 판단할 수 있도록 합니다.

documents/oracle-database/<version>/<document-family>/<file-name>.pdf

이번 배치 예시입니다.

documents/
└── oracle-database/
├── 26ai/
...

문서 인벤토리(Document Inventory)는 PDF와는 다른 Prefix에 배치합니다.

catalog/document_inventory/current/document_inventory.parquet

이러한 분리에는 다음과 같은 장점이 있습니다.

• PDF와 구조화된 데이터(Structured Data)를 별도로 관리할 수 있음
• Parquet 전용 Prefix를 Autonomous AI Database나 다른 데이터 처리 기반에서 지정할 수 있음
• 제3회 RAG 대상 Prefix를 PDF로만 한정할 수 있음
• 하베스트(Harvest) 결과를 확인하기 쉬움

이번 문서 인벤토리에서는 다음 항목을 관리합니다.

oci://<bucket>@<namespace>/<object-name>

형식은 OCI Data Flow나 Spark/Hadoop에서 Object Storage를 참조할 때 사용됩니다.

반면, Autonomous AI Database의 DBMS_CLOUD에서는 Object Storage 상의 파일을 참조하는 URI로 https://로 시작하는 HTTPS URI를 지정합니다. Select AI with RAG에서도 Vector Index의 입력원이 되는 Object Storage의 위치를 HTTPS URI로 지정합니다.

이번에는 제3회와 제4회에서 Autonomous AI Database로부터 재사용하기 위해, object_uri에는 PDF별 HTTPS Object URI를 저장합니다.

도쿄 리전(Tokyo Region)을 포함한 상용 렐름(Commercial Realm, OC1)에서는 다음의 Object Storage Dedicated Endpoint 형식을 사용합니다.

예를 들어, 이번 PDF는 다음 형식이 됩니다.

Object 이름에 공백, 일본어, #, ? 등이 포함되는 경우에 대비하여, Python에서는 urllib.parse.quote()를 사용하여 Object 이름을 URL 인코딩합니다. Prefix를 나타내는 /는 구분자로 남겨둡니다.

단, Select AI with RAG에서는 멀티바이트 문자(Multi-byte character)를 포함하는 입력 문서의 파일명이 Vectorization 과정에서 스킵되므로, RAG 대상 PDF 파일명에는 영문자, 숫자, 하이픈(-), 언더스코어(_)를 사용합니다.

object_uri는 각 행의 PDF를 가리키는 URI입니다. 제4회에서 document_inventory.parquet 자체를 외부 테이블(External Table)로 참조할 때는 다음의 Parquet 파일용 HTTPS URI를 별도로 사용합니다. https://<namespace>.objectstorage.<region>.oci.customer-oci.com/n/<namespace>/b/<bucket>/o/catalog/document_inventory/current/document_inventory.parquet

참고:

CSV를 타입 추론(Type Inference)만으로 읽어들이면 12.2가 숫자로 취급될 수 있습니다. 제품 버전은 계산하는 값이 아니라 식별자(Identifier)이므로, 반드시 문자열(String)로 취급해야 합니다.

26ai → string
19c → string
12.2 → string

Oracle Database 매뉴얼의 표지에는 날짜가 아닌 July 2026과 같이 년월만 기재되는 경우가 있습니다. 존재하지 않는 날짜를 2026-07-01로 보완하면 원본 데이터보다 높은 정밀도의 날짜를 만들게 됩니다. 따라서 이번에는 다음과 같이 두 개의 열로 나눕니다.

publication_year = 2026
publication_month = 7

document_id는 버전을 포함한 문서 단위의 고유 ID(Unique ID)입니다.

oracle_db_26ai_admin
oracle_db_19c_admin
oracle_db_12_2_admin

document_family_id는 버전을 가로지르는 문서 계열의 ID입니다.

database_administrator_guide

제4회에서는 다음과 같은 JOIN에 사용할 수 있습니다.

SELECT
i.document_id,
i.product_version,
...

로컬 PC 또는 OCI Cloud Shell에서 문서 인벤토리 CSV와 Parquet를 생성할 환경을 준비합니다.

이번 절차에서는 다음 환경을 전제로 합니다.

• OCI 계정을 사용할 수 있을 것
• OCI Object Storage의 Bucket을 생성할 수 있을 것
• OCI Data Catalog 인스턴스가 생성되어 있을 것
• Data Catalog를 조작하는 IAM 권한이 부여되어 있을 것
• Data Catalog용 Dynamic Group을 생성할 수 있을 것
• Python 3.10 이상을 사용할 수 있을 것
• pandas와 pyarrow를 설치할 수 있을 것
• 사용 조건을 확인한 후, 대상 PDF를 미리 준비해 둘 것

이번에는 제1회에서 작성한 Data Catalog 인스턴스와 Object Storage Data Asset을 재사용하여, 문서용 Bucket과 Resource Principal Connection을 추가합니다.

본 기사에서는 다음 값을 사용합니다. 실제 환경에 맞춰 변경하여 사용해 주세요.

1) 작업용 디렉토리 생성

mkdir -p oracle-document-catalog/{data,documents/oracle-database,scripts,output}
cd oracle-document-catalog

2) PDF 배치용 디렉토리 생성

mkdir -p documents/oracle-database/26ai/{admin,installation_linux,concepts,vector_search}
mkdir -p documents/oracle-database/19c/{admin,installation_linux,concepts}
mkdir -p documents/oracle-database/12.2/{admin,installation_linux,concepts}

3) 준비한 PDF 배치

documents/oracle-database/26ai/admin/database-administrators-guide.pdf
documents/oracle-database/26ai/installation_linux/oracle-ai-database-installation-guide-linux.pdf
documents/oracle-database/26ai/concepts/database-concepts.pdf
...

4) 배치 결과 확인

% find documents -type f -name '*.pdf' | sort
documents/oracle-database/12.2/admin/database-administrators-guide.pdf
documents/oracle-database/12.2/concepts/database-concepts.pdf
...

・ pdf 파일 수 확인

10개의 파일이 표시되는지 확인합니다.

% find documents -type f -name '*.pdf' | wc -l
10

1) data/document_inventory.csv 생성

document_id,document_family_id,product_name,product_version,document_title,document_type,category,subcategory,language_code,document_number,publication_year,publication_month,official_url,object_name,rag_enabled,document_priority,data_owner,tags
oracle_db_26ai_admin,database_administrator_guide,Oracle AI Database,26ai,Database Administrator's Guide,guide,administration,database_administration,en,G42927-08,2026,7,https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/index.html,documents/oracle-database/26ai/admin/database-administrators-guide.pdf,true,10,database_platform_team,oracle_database|26ai|dba|administration
oracle_db_26ai_ladbi,database_installation_guide_linux,Oracle AI Database,26ai,Oracle AI Database Installation Guide for Linux,installation_guide,installation,linux,en,G43069-07,2026,7,https://docs.oracle.com/en/database/oracle/oracle-database/26/ladbi/index.html,documents/oracle-database/26ai/installation_linux/oracle-ai-database-installation-guide-linux.pdf,true,20,database_platform_team,oracle_database|26ai|installation|linux
...

CSV 내 문서 번호와 발행 연월은 예시입니다. Object Storage에 배치된 PDF 버전과 일치하는지 확인하십시오.

2) CSV의 행 수 확인

헤더를 제외하고 10행임을 확인합니다.

% tail -n +2 data/document_inventory.csv | wc -l
10

3) CSV의 시작 부분 확인

% head -n 3 data/document_inventory.csv
document_id,document_family_id,product_name,product_version,document_title,document_type,category,subcategory,language_code,document_number,publication_year,publication_month,official_url,object_name,rag_enabled,document_priority,data_owner,tags
oracle_db_26ai_admin,database_administrator_guide,Oracle AI Database,26ai,Database Administrator's Guide,guide,administration,database_administration,en,G42927-08,2026,7,https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/index.html,documents/oracle-database/26ai/admin/database-administrators-guide.pdf,true,10,database_platform_team,oracle_database|26ai|dba|administration
...

1) Python 버전 확인

1) Python 버전 확인

% python3 --version
Python 3.14.3

2) 가상 환경 생성

% python3 -m venv .venv
% source .venv/bin/activate

Windows PowerShell의 경우 다음처럼 활성화합니다.

.venv\Scripts\Activate.ps1

3) requirements.txt 생성

% vi requirements.txt
% cat requirements.txt
pandas>=2.2.0
...

4) 패키지 설치

% python -m pip install --upgrade pip
% python -m pip install -r requirements.txt

5) 설치 결과 확인

% python -c "import pandas, pyarrow; print('pandas:', pandas.__version__).__print('pyarrow:', pyarrow.__version__)"
pandas: 3.0.5
pyarrow: 25.0.0

이번 스크립트에서는 단순히 pandas.DataFrame.to_parquet()만 실행하는 것이 아니라, 다음 검증을 수행합니다.

• 필수 컬럼 존재 확인
• 필수 값의 공란 확인
• document_id 형식 확인 -
• document_id 중복 확인 -
• object_name 중복 확인 -
• rag_enabled Boolean 변환 - 발행 연도, 발행 월, 우선순위의 숫자 변환
• 발행 월이 1부터 12까지인지 확인
• Oracle 공식 URL인지 확인
• Object 이름이 PDF인지 확인
• PyArrow Schema를 이용한 명시적인 Parquet 타입 지정
• 생성 후 Parquet 재읽기 및 스키마 확인

1) scripts/create_document_inventory.py 생성

from __future__ import annotations
import argparse
import re
...

1) Object Storage 네임스페이스 확인

OCI CLI를 사용할 수 있는 경우, 다음 명령어로 확인할 수 있습니다.

% oci os ns get --query data --raw-output
<your-namespace>

2) 환경 변수 설정

export OCI_NAMESPACE='<your-namespace>'
export OCI_REGION='ap-tokyo-1'
export OCI_BUCKET='oracle-database-doc-catalog'

3) Python 스크립트 실행