버전: In Development

Types

aerospike-py는 반환값에 NamedTuple 클래스를, 입력 파라미터에 TypedDict 클래스를 사용합니다. 모든 타입은 최상위 패키지 또는 aerospike_py.types에서 import할 수 있습니다.

from aerospike_py import Record, ExistsResult, ReadPolicy, WritePolicy, WriteMeta
# 또는
from aerospike_py.types import Record, ExistsResult, ReadPolicy, WritePolicy, WriteMeta

반환 타입 (NamedTuple)

NamedTuple 반환 타입은 속성 접근과 튜플 언패킹을 모두 지원합니다 (하위 호환성).

`Record`

읽기 및 operate 메서드가 반환하는 전체 레코드입니다.

필드	타입	설명
`key`	`AerospikeKey \| None`	레코드 키 (`POLICY_KEY_DIGEST`이면 `None`)
`meta`	`RecordMetadata \| None`	레코드 메타데이터
`bins`	`dict[str, Any] \| None`	빈 이름-값 쌍

반환하는 메서드: get(), select(), operate(), Query.results()

record: Record = client.get(key)
print(record.meta.gen)   # 속성 접근
print(record.bins)       # {"name": "Alice", "age": 30}

key, meta, bins = record  # 튜플 언패킹 (하위 호환)

`RecordMetadata`

generation과 TTL을 포함하는 레코드 메타데이터입니다.

필드	타입	설명
`gen`	`int`	레코드 generation (낙관적 잠금 버전)
`ttl`	`int`	레코드 TTL (초 단위)

record = client.get(key)
print(record.meta.gen)  # 1
print(record.meta.ttl)  # 2591998

`AerospikeKey`

서버가 반환하는 레코드 키입니다.

필드	타입	설명
`namespace`	`str`	네임스페이스 이름
`set_name`	`str`	세트 이름
`user_key`	`str \| int \| bytes \| None`	사용자 제공 기본 키 (`POLICY_KEY_DIGEST`이면 `None`)
`digest`	`bytes`	20바이트 RIPEMD-160 다이제스트

record = client.get(key, policy={"key": aerospike_py.POLICY_KEY_SEND})
print(record.key.namespace)   # "test"
print(record.key.set_name)    # "demo"
print(record.key.user_key)    # "user1"

`BatchRecord`

배치 작업 내의 개별 레코드 결과입니다 (BatchWriteResult.batch_records 내부).

필드	타입	설명
`key`	`AerospikeKey \| None`	레코드 키
`result`	`int`	개별 레코드 결과 코드 (0 = 성공)
`record`	`Record \| None`	레코드 데이터 (작업 실패 시 `None`)
`in_doubt`	`bool`	일시적 전송 오류 후에도 쓰기가 완료됐을 수 있는지 (기본값 `False`). PR-374에서 추가됨 — 기존의 `key, result, record = br` 위치 언패킹 코드는 깨지므로 속성 접근(`br.in_doubt`)으로 마이그레이션.

results = client.batch_operate(keys, ops)
for br in results.batch_records:
    if br.result == 0 and br.record is not None:
        print(br.record.bins)

`BatchWriteResult`

배치 쓰기 작업의 전체 결과를 담는 NamedTuple 컨테이너입니다.

반환하는 메서드: batch_write(), batch_operate(), batch_remove(), batch_write_numpy() (sync 및 async). sync 및 async batch_read()는 LazyBatchRecords를 반환합니다.

필드	타입	설명
`batch_records`	`list[BatchRecord]`	개별 레코드 결과 리스트

`BatchRecords`

TypeAlias = dict[UserKey, AerospikeRecord]. import-compat 용도로 유지되는 historical alias. PR-374에서 batch_read()는 LazyBatchRecords를 반환하도록 바뀌었고, 해당 핸들에서 .to_dict()를 호출하면 이 alias가 지칭하는 dict shape와 동일한 결과를 얻습니다. 현재 어떤 메서드도 이 alias를 직접 반환하지 않습니다.

`LazyBatchRecords`

반환하는 메서드: sync 및 async batch_read() — raw Rust 결과를 zero-conversion으로 감싼 핸들. Materialise는 명시적 메서드 호출(또는 dict-style Mapping dunder — lazy + cached to_dict() view 위에서 동작)로 지연됩니다.

메서드 / 속성	타입	설명
`to_dict()`	`dict[UserKey, dict[str, Any]]`	`dict[user_key, bins_dict]`로 materialise. digest-only 및 실패한 record는 제외됨.
`to_numpy(dtype)`	`NumpyBatchRecords`	구조화 배열로 materialise. `dtype`은 `np.dtype` 객체여야 합니다 (예: `np.dtype([("age","<i4"),("height","<f4"),("name","S10")])`). 각 dtype field 이름은 동일 이름의 bin에 매핑됩니다 — list-of-tuples shorthand나 단일 field string은 auto-promote 되지 않으니 `np.dtype(...)`으로 감싸세요. per-record fill loop은 `py.detach`로 GIL을 release하므로 sibling 작업(torch 추론, 다른 asyncio task)이 fill 중에도 GIL을 잡을 수 있습니다. 실패/missing reads (`result_code != 0`)는 dtype의 zero value로 남으므로, downstream 연산 전 `result_codes`로 마스킹하세요.
`batch_records`	`list[BatchRecord]`	Compat 경로: lazy NamedTuple 변환.
`found_count()`	`int`	성공 record 수 (변환 없음).
`keys()`	`dict_keys`	dict-style keys view — `to_dict().keys()`와 동일 (missing/실패 제외).
`all_user_keys()`	`list[UserKey \| None]`	모든 batch record의 `user_key`를 request 순서대로 — `batch_records` / `NumpyBatchRecords` data array와 positional 정렬됨. digest-only 요청 슬롯은 `None`이 들어가 `zip(handle.all_user_keys(), handle.batch_records)`가 모든 record를 그 요청 키 (또는 `None`)와 짝지을 수 있습니다.
`iter_records()`	`Iterator[BatchRecord]`	모든 record (digest-only 및 실패 포함)를 삽입 순서로 순회.
`items()` / `values()` / `__iter__`	dict views	dict-like 하위 호환 — cached `to_dict()`와 동일 시맨틱.
`lazy_records[user_key]`	`dict[str, Any]`	dict-style item 접근 (`__getitem__`).
`user_key in lazy_records`	`bool`	dict-style 멤버십 (`__contains__`).
`lazy_records.get(user_key, default=None)`	`dict[str, Any] \| Any`	dict-style `get` — `dict.get` 시맨틱 동일.
`len(lazy_records)`	`int`	Dict-view cardinality — `len(lazy_records.to_dict())` 일치 (user_key + record body 있는 성공 read만). 빠름: 순수 Rust filter+count로 PyDict 할당 없음. raw record 수 (missing/실패 포함)는 `len(lazy_records.batch_records)` 사용.
`release_cache()`	`None`	첫 Mapping 접근 / `to_dict()`에서 build된 cached `PyDict`를 drop. raw Rust records(따라서 `batch_records`, `iter_records()`, `all_user_keys()`, `found_count()`, `to_numpy(dtype)`)는 유지. 후속 Mapping 접근은 lazy하게 cache를 재build. 큰 배치 materialise 후 더이상 dict가 필요하지 않을 때 유용.

`ExistsResult`

존재 여부 확인 결과입니다.

필드	타입	설명
`key`	`AerospikeKey \| None`	레코드 키
`meta`	`RecordMetadata \| None`	메타데이터 (레코드가 없으면 `None`)

반환하는 메서드: exists()

result: ExistsResult = client.exists(key)
if result.meta is not None:
    print(f"gen={result.meta.gen}")

_, meta = result  # 튜플 언패킹

`InfoNodeResult`

클러스터 노드별 info 명령 결과입니다.

필드	타입	설명
`node_name`	`str`	클러스터 노드 이름
`error_code`	`int`	성공 시 0
`response`	`str`	Info 응답 문자열

반환하는 메서드: info_all()

results: list[InfoNodeResult] = client.info_all("namespaces")
for result in results:
    print(f"{result.node_name}: {result.response}")

`OperateOrderedResult`

operate_ordered()의 순서 보존 결과입니다.

필드	타입	설명
`key`	`AerospikeKey \| None`	레코드 키
`meta`	`RecordMetadata \| None`	레코드 메타데이터
`ordered_bins`	`list[BinTuple]`	순서가 보존된 연산 결과

반환하는 메서드: operate_ordered()

result: OperateOrderedResult = client.operate_ordered(key, ops)
for bin_tuple in result.ordered_bins:
    print(f"{bin_tuple.name} = {bin_tuple.value}")

`BinTuple`

순서 보존 결과에서 사용되는 단일 빈 이름-값 쌍입니다.

필드	타입	설명
`name`	`str`	빈 이름
`value`	`Any`	빈 값

API → 반환 타입 빠른 참조

메서드	반환 타입
`get()`, `select()`	`Record`
`exists()`	`ExistsResult`
`operate()`	`Record`
`operate_ordered()`	`OperateOrderedResult`
`info_all()`	`list[InfoNodeResult]`
`batch_read()` (sync 및 async)	`LazyBatchRecords` (→ `.to_dict()` 또는 `.to_numpy(dtype)`로 materialise)
`batch_write()`, `batch_operate()`, `batch_remove()`	`BatchWriteResult` (`batch_records: list[BatchRecord]`)
`batch_write_numpy()`	`BatchWriteResult`
`Query.results()`	`list[Record]`

입력 타입 (TypedDict)

TypedDict 입력 타입은 policy 및 meta 파라미터에 대한 IDE 자동완성과 타입 체크를 제공합니다. 모든 필드는 선택적(total=False)입니다.

`ClientConfig`

클라이언트 생성을 위한 설정 딕셔너리입니다.

사용하는 메서드: aerospike_py.client(config), AsyncClient(config)

필드	타입	기본값	설명
`hosts`	`list[tuple[str, int]]`	필수	클러스터 시드 노드
`cluster_name`	`str`		예상 클러스터 이름
`auth_mode`	`int`	`AUTH_INTERNAL`	인증 모드 (`AUTH_INTERNAL`, `AUTH_EXTERNAL`, `AUTH_PKI`)
`user`	`str`		인증 사용자명
`password`	`str`		인증 비밀번호
`timeout`	`int`	`1000`	연결 타임아웃 (ms)
`idle_timeout`	`int`		연결 유휴 타임아웃 (ms)
`max_conns_per_node`	`int`		노드당 최대 연결 수
`min_conns_per_node`	`int`		노드당 최소 연결 수
`tend_interval`	`int`		클러스터 tend 간격 (ms)
`use_services_alternate`	`bool`	`False`	대체 서비스 주소 사용

config: ClientConfig = {
    "hosts": [("127.0.0.1", 3000)],
    "cluster_name": "docker",
    "timeout": 5000,
}
client = aerospike_py.client(config).connect()

`ReadPolicy`

읽기 작업을 위한 정책입니다.

사용하는 메서드: get(), select(), exists()

필드	타입	기본값	설명
`socket_timeout`	`int`	`30000`	소켓 유휴 타임아웃 (ms)
`total_timeout`	`int`	`1000`	전체 트랜잭션 타임아웃 (ms)
`max_retries`	`int`	`2`	최대 재시도 횟수
`sleep_between_retries`	`int`	`0`	재시도 간 대기 시간 (ms)
`timeout_delay`	`int`	`0`	데드라인을 지난 요청을 타임아웃 처리하기 전 대기 시간 (ms). 소켓을 비우고 재사용된 연결에서 오래된 응답을 읽지 않도록 합니다.
`filter_expression`	`Any`		`aerospike_py.exp`로 빌드한 Expression 필터
`replica`	`int`	`POLICY_REPLICA_SEQUENCE`	레플리카 알고리즘
`read_mode_ap`	`int`	`POLICY_READ_MODE_AP_ONE`	AP 읽기 일관성 수준

policy: ReadPolicy = {
    "total_timeout": 5000,
    "max_retries": 3,
}
record = client.get(key, policy=policy)

`WritePolicy`

쓰기 작업을 위한 정책입니다.

사용하는 메서드: put(), remove(), touch(), append(), prepend(), increment(), remove_bin(), operate(), operate_ordered()

필드	타입	기본값	설명
`socket_timeout`	`int`	`30000`	소켓 유휴 타임아웃 (ms)
`total_timeout`	`int`	`1000`	전체 트랜잭션 타임아웃 (ms)
`max_retries`	`int`	`0`	최대 재시도 횟수
`timeout_delay`	`int`	`0`	데드라인을 지난 요청을 타임아웃 처리하기 전 대기 시간 (ms).
`durable_delete`	`bool`	`False`	영구 삭제 사용 (Enterprise 전용)
`key`	`int`	`POLICY_KEY_DIGEST`	키 전송 정책 (`POLICY_KEY_DIGEST`, `POLICY_KEY_SEND`)
`exists`	`int`	`POLICY_EXISTS_IGNORE`	존재 정책 (`POLICY_EXISTS_*`)
`gen`	`int`	`POLICY_GEN_IGNORE`	Generation 정책 (`POLICY_GEN_IGNORE`, `POLICY_GEN_EQ`, `POLICY_GEN_GT`)
`commit_level`	`int`	`POLICY_COMMIT_LEVEL_ALL`	커밋 수준 (`POLICY_COMMIT_LEVEL_ALL`, `POLICY_COMMIT_LEVEL_MASTER`)
`ttl`	`int`	`0`	레코드 TTL (초)
`filter_expression`	`Any`		`aerospike_py.exp`로 빌드한 Expression 필터

policy: WritePolicy = {
    "key": aerospike_py.POLICY_KEY_SEND,
    "exists": aerospike_py.POLICY_EXISTS_CREATE_ONLY,
}
client.put(key, bins, policy=policy)

`BatchPolicy`

배치 작업을 위한 정책입니다.

사용하는 메서드: batch_read(), batch_operate(), batch_remove()

필드	타입	기본값	설명
`socket_timeout`	`int`	`30000`	소켓 유휴 타임아웃 (ms)
`total_timeout`	`int`	`1000`	전체 트랜잭션 타임아웃 (ms)
`max_retries`	`int`	`2`	최대 재시도 횟수
`timeout_delay`	`int`	`0`	데드라인을 지난 요청을 타임아웃 처리하기 전 대기 시간 (ms).
`concurrency`	`int`	`BATCH_CONCURRENCY_PARALLEL`	노드별 분산 모드. `BATCH_CONCURRENCY_SEQUENTIAL`(노드 순차) 또는 `BATCH_CONCURRENCY_PARALLEL`(전체 병렬, 기본값). Batch Concurrency 상수 참조. 다른 값은 `ValueError`를 발생시킵니다.
`filter_expression`	`Any`		Expression 필터

policy: BatchPolicy = {"total_timeout": 10000}
batch = client.batch_read(keys, policy=policy)

`QueryPolicy`

쿼리 작업을 위한 정책입니다.

사용하는 메서드: Query.results(), Query.foreach()

필드	타입	기본값	설명
`socket_timeout`	`int`	`30000`	소켓 유휴 타임아웃 (ms)
`total_timeout`	`int`	`0`	전체 트랜잭션 타임아웃 (0 = 제한 없음)
`max_retries`	`int`	`2`	최대 재시도 횟수
`timeout_delay`	`int`	`0`	데드라인을 지난 요청을 타임아웃 처리하기 전 대기 시간 (ms).
`max_records`	`int`	`0`	최대 반환 레코드 수 (0 = 전부)
`records_per_second`	`int`	`0`	속도 제한 (0 = 무제한)
`filter_expression`	`Any`		`aerospike_py.exp`로 빌드한 Expression 필터

policy: QueryPolicy = {"max_records": 100}
records = query.results(policy=policy)

`ScanPolicy`

스캔 작업을 위한 정책입니다. 공식 Aerospike Python C 클라이언트의 ScanPolicy를 미러링합니다.

aerospike-core 2.0 크레이트는 아직 별도의 ScanPolicy 구조체를 노출하지 않으므로, 현재 스캔 호출은 QueryPolicy 파서를 경유합니다. 향후 aerospike-core에 전용 ScanPolicy가 추가되면 사용자 측 타입 변경 없이 내부에서 새 파서로 전환됩니다. issue #316 참조.

사용하는 메서드: client.scan() 및 predicate 없는 client.query()

필드	타입	기본값	설명
`socket_timeout`	`int`	`30000`	소켓 유휴 타임아웃 (ms)
`total_timeout`	`int`	`0`	전체 트랜잭션 타임아웃 (0 = 제한 없음)
`max_retries`	`int`	`2`	최대 재시도 횟수
`timeout_delay`	`int`	`0`	데드라인을 지난 요청을 타임아웃 처리하기 전 대기 시간 (ms).
`filter_expression`	`Any`		`aerospike_py.exp`로 빌드한 Expression 필터
`replica`	`int`	`POLICY_REPLICA_SEQUENCE`	레플리카 알고리즘
`read_mode_ap`	`int`	`POLICY_READ_MODE_AP_ONE`	AP 읽기 일관성 수준
`records_per_second`	`int`	`0`	노드당 속도 제한 (0 = 무제한; 서버 4.7+)
`max_records`	`int`	`0`	최대 반환 레코드 수 근사값 (0 = 전부; 서버 6.0+)
`durable_delete`	`bool`	`False`	백그라운드 스캔-쓰기에서 영구 삭제 사용 (Enterprise 3.10+)
`ttl`	`int`	`0`	백그라운드 스캔-쓰기의 기본 TTL
`partition_filter`	`PartitionFilter`	(4096개 전부)	스캔할 파티션 부분집합. `aerospike_py.partition_filter_*()` 헬퍼로 생성.

`BatchUDFPolicy`

batch_apply()를 위한 배치-레벨 UDF 정책입니다. 레코드 단위 오버라이드는 BatchUDFMeta에 둡니다. 전송-레벨 옵션(타임아웃, 재시도, concurrency 등)은 BatchPolicy에 위치하며, batch_apply()에 전달하는 동일한 정책 딕셔너리에 머지됩니다.

사용하는 메서드: batch_apply()

필드	타입	기본값	설명
`commit_level`	`int`	`POLICY_COMMIT_LEVEL_ALL`	커밋 수준 (`POLICY_COMMIT_LEVEL_ALL` / `_MASTER`)
`ttl`	`int`	`0`	레코드 TTL (초). `0` = 네임스페이스 기본, `-1` = 만료 안 함, `-2` = 업데이트 안 함
`key`	`int`	`POLICY_KEY_DIGEST`	키 전송 정책 (`POLICY_KEY_DIGEST` / `POLICY_KEY_SEND`)
`durable_delete`	`bool`	`False`	UDF가 레코드를 삭제할 때 영구 삭제 (Enterprise 3.10+)
`filter_expression`	`Any`		각 레코드에 적용되는 Expression 필터. 필터에 걸린 레코드는 `BatchRecord.result == FILTERED_OUT`을 반환합니다.

`BatchUDFMeta`

batch_apply()의 레코드 단위 메타입니다. keys 인자에서 (key, meta) 튜플의 두 번째 요소로 전달합니다. BatchDeleteMeta와 동일한 단일 평면 dict 형태이며, UDF 호출 형태와 정책 필드를 동시에 오버라이드할 수 있습니다.

필드	타입	설명
`module`	`str`	이 레코드의 UDF 모듈명 오버라이드. 미지정 시 `batch_apply()`의 `module` 인자 사용.
`function`	`str`	이 레코드의 UDF 함수명 오버라이드.
`args`	`list[Any]`	인자 리스트 오버라이드. `[]`을 명시적으로 전달하면 기본 args를 비웁니다.
`ttl`	`int`	이 레코드의 TTL 오버라이드 (초; `WriteMeta.ttl`과 동일 시맨틱).
`commit_level`	`int`	커밋 수준 오버라이드.
`key`	`int`	키 전송 정책 오버라이드 (`POLICY_KEY_DIGEST` / `POLICY_KEY_SEND`).
`durable_delete`	`bool`	영구 삭제 오버라이드.

노트

filter_expression은 BatchUDFMeta에서 받지 않습니다 — 배치-레벨 BatchUDFPolicy에서 설정하세요. (aerospike-core 2.0에서 레코드 단위 filter_expression은 와이어링되지 않으며, BatchDeleteMeta와 같은 형태입니다.)

# 모든 키에 동일한 UDF 적용
keys = [("test", "demo", f"u_{i}") for i in range(10)]
results = client.batch_apply(keys, "my_udf", "increment_counter", [1])

# 레코드별 오버라이드: 한 레코드만 다른 args/긴 TTL
results = client.batch_apply(
    [
        ("test", "demo", "u_1"),  # 기본 args 사용
        (("test", "demo", "u_2"), {"args": [5], "ttl": 3600}),
    ],
    "my_udf", "increment_counter", args=[1],
)

`AdminPolicy`

관리 작업을 위한 정책입니다.

사용하는 메서드: admin_create_user(), admin_drop_user(), admin_change_password(), admin_grant_roles(), admin_revoke_roles(), admin_query_user_info(), admin_query_users_info(), admin_create_role(), admin_drop_role(), admin_grant_privileges(), admin_revoke_privileges(), admin_query_role(), admin_query_roles(), admin_set_whitelist(), admin_set_quotas()

필드	타입	기본값	설명
`timeout`	`int`	`1000`	관리 작업 타임아웃 (ms)

policy: AdminPolicy = {"timeout": 5000}
client.admin_create_user("user", "pass", ["read-write"], policy=policy)

`WriteMeta`

쓰기 작업의 메타데이터입니다.

사용하는 메서드: put(), remove(), touch(), append(), prepend(), increment(), remove_bin(), operate(), operate_ordered() — meta 파라미터로 사용

필드	타입	설명
`gen`	`int`	낙관적 잠금을 위한 예상 generation (`POLICY_GEN_EQ`와 함께 사용)
`ttl`	`int`	레코드 TTL (초 단위)

# TTL 설정
meta: WriteMeta = {"ttl": 300}
client.put(key, bins, meta=meta)

# 낙관적 잠금
record = client.get(key)
meta: WriteMeta = {"gen": record.meta.gen}
client.put(key, new_bins, meta=meta, policy={"gen": aerospike_py.POLICY_GEN_EQ})

`Privilege`

관리자 역할 관리를 위한 권한 정의입니다.

사용하는 메서드: admin_create_role(), admin_grant_privileges(), admin_revoke_privileges()

필드	타입	설명
`code`	`int`	권한 코드 (`PRIV_READ`, `PRIV_WRITE`, `PRIV_READ_WRITE` 등)
`ns`	`str`	네임스페이스 범위 (빈 문자열이면 글로벌)
`set`	`str`	세트 범위 (빈 문자열이면 네임스페이스 전체)

privilege: Privilege = {
    "code": aerospike_py.PRIV_READ_WRITE,
    "ns": "test",
    "set": "demo",
}
client.admin_create_role("custom_role", [privilege])

`UserInfo`

관리자 쿼리가 반환하는 사용자 정보입니다.

반환하는 메서드: admin_query_user_info(), admin_query_users_info()

필드	타입	설명
`user`	`str`	사용자명
`roles`	`list[str]`	할당된 역할 이름
`conns_in_use`	`int`	활성 연결 수

`RoleInfo`

관리자 쿼리가 반환하는 역할 정보입니다.

반환하는 메서드: admin_query_role(), admin_query_roles()

필드	타입	설명
`name`	`str`	역할 이름
`privileges`	`list[Privilege]`	할당된 권한
`allowlist`	`list[str]`	IP 허용 목록
`read_quota`	`int`	읽기 쿼터
`write_quota`	`int`	쓰기 쿼터

반환 타입 (NamedTuple)​

Record​

RecordMetadata​

AerospikeKey​

BatchRecord​

BatchWriteResult​

BatchRecords​

LazyBatchRecords​

ExistsResult​

InfoNodeResult​

OperateOrderedResult​

BinTuple​

API → 반환 타입 빠른 참조​

입력 타입 (TypedDict)​

ClientConfig​

ReadPolicy​

WritePolicy​

BatchPolicy​

QueryPolicy​

ScanPolicy​

BatchUDFPolicy​

BatchUDFMeta​

AdminPolicy​

WriteMeta​

Privilege​

UserInfo​

RoleInfo​