スクリプト開発 / 簡易キャッシュ `DFF.CACHE`

DFF.CACHE は Redis ベースの一時キャッシュで、構造は scope + key -> value です。カウンター、キュー、セット、軽量メッセージパブリッシュに適しています。

JSON 型を保持する必要がある場合や、小規模なアプリケーション状態を永続保存する場合は、DFF.STORE を使用してください。

主な違い

読み出したスカラー値は通常文字列のため、業務タイプに応じて int(...)、float(...) または json.loads(...) を呼び出す必要があります。
デフォルトの scope は現在の Script ID です。複数の Script 間でデータを共有するには、同じ scope を明示的に渡す必要があります。
各 Key とパブリッシュ Topic は Scope ごとに分離され、返される Key 名には内部の Scope プレフィックスは含まれません。
hstrlenall(...) は {field: valueのバイト長} を返します。長さの単位はバイトであり、Unicode 文字数ではありません。

API 早見表

Key

メソッド	説明
`type(key, scope=None)`	Key のデータ型を返す
`keys(pattern='*', scope=None)`	一致する Key を返す
`exists(key, scope=None)`	Key が存在するか判定する
`expire(key, expires, scope=None)`	残り有効期限（秒）を設定する
`expireat(key, timestamp, scope=None)`	UNIX 秒タイムスタンプ形式の有効期限を設定する
`ttl(key, scope=None)` / `pttl(key, scope=None)`	残り有効期限を返す。単位はそれぞれ秒とミリ秒
`rename(key, new_key, scope=None)`	Key をリネームする
`renamenx(key, new_key, scope=None)`	ターゲットが存在しない場合のみ Key をリネームする
`delete(key, scope=None)`	単一の Key を削除する。リスト / タプルを渡すと一括削除する
`delete_pattern(pattern, scope=None)`	一致する Key を削除する。`pattern` は必須

String

メソッド	説明
`set(key, value, expires=None, not_exists=False, exists=False, scope=None)`	値を書き込む。Key の存在状態と有効期限秒数を制限できる
`mset(key_values, scope=None)`	一括書き込み。同時に有効期限を設定することはできない
`get(key, scope=None)` / `DFF.CACHE(key, scope=None)`	単一の値を読み取る
`mget(keys, scope=None)`	一括読み取り
`get_pattern(pattern, scope=None)`	一致する `{key: value}` を返す
`getset(key, value, scope=None)`	新しい値を書き込み、古い値を返す
`incr(key, step=1, scope=None)` / `incrby(key, step, scope=None)`	整数値を増加させる

Hash

メソッド	説明
`hkeys(key, pattern='*', with_values=False, scope=None)`	一致するフィールドを返す。`with_values=True` の場合は値も同時に返す
`hset(key, field, value, not_exists=False, scope=None)`	フィールドを書き込む
`hsetnx(key, field, value, scope=None)`	フィールドが存在しない場合のみ書き込む
`hmset(key, field_values, scope=None)`	フィールドを一括書き込みする
`hget(key, field, scope=None)`	フィールドを読み取る
`hstrlen(key, field, scope=None)` / `hstrlenall(key, scope=None)`	1つまたはすべてのフィールド値のバイト長を返す
`hmget(key, fields, scope=None)`	フィールドを一括読み取りする
`hgetall(key, scope=None)`	すべてのフィールドと値を読み取る
`hincr(key, field, step=1, scope=None)` / `hincrby(key, field, step, scope=None)`	整数フィールド値を増加させる
`hdel(key, field, scope=None)`	単一のフィールドを削除する。リスト / タプルを渡すと一括削除する

List

メソッド	説明
`lpush(key, value, scope=None)` / `rpush(key, value, scope=None)`	左側 / 右側から1つの値または値のリストをプッシュする
`lpop(key, count=None, scope=None)` / `rpop(key, count=None, scope=None)`	左側 / 右側から1つまたは複数の値をポップする
`blpop(key, timeout=0, scope=None)` / `brpop(key, timeout=0, scope=None)`	ブロッキングポップ
`rpoplpush(key, dest_key=None, scope=None, dest_scope=None)`	ソースリストの右側からポップし、ターゲットリストの左側にプッシュする
`brpoplpush(key, dest_key=None, timeout=0, scope=None, dest_scope=None)`	ブロッキングでポップしてプッシュする
`llen(key, scope=None)`	リストの長さを返す
`lrange(key, start=0, stop=-1, scope=None)`	指定した範囲を返す
`ltrim(key, start, stop, scope=None)`	指定した範囲のみを保持する

blpop(...) と brpop(...) は [元のキー名, value] を返し、タイムアウト時は [None, None] を返します。rpoplpush(...) と brpoplpush(...) で宛先 Key を省略するとソース Key が使用され、dest_scope を使用して明確に Scope をまたいだ移動ができます。

Set

メソッド	説明
`sadd(key, member, scope=None)` / `srem(key, member, scope=None)`	メンバーまたはメンバーリストを追加 / 削除
`scard(key, scope=None)`	メンバー数を返す
`smembers(key, scope=None)`	すべてのメンバーを返す
`sismember(key, member, scope=None)`	メンバーが存在するかどうかを判定する

ZSet

メソッド	説明
`zadd(key, member_scores, scope=None)` / `zrem(key, member, scope=None)`	メンバーを追加 / 削除
`zcard(key, scope=None)`	メンバー数を返す
`zrange(key, start=0, stop=-1, with_scores=False, scope=None)`	位置に基づいてメンバーを返す
`zrangebyscore(key, min_score='-inf', max_score='+inf', with_scores=False, scope=None)`	スコアに基づいてメンバーを返す
`zpop_below_all(key, score, scope=None)` / `zpop_above_all(key, score, scope=None)`	指定スコア以下 / 以上のすべてのメンバーをポップする
`zpop_below_lpush_all(key, dest_key, score, scope=None)` / `zpop_above_lpush_all(key, dest_key, score, scope=None)`	スコア条件を満たすメンバーをポップし、ターゲットリストにプッシュします。

ZSet のポップまたは移動拡張を実行する前に、ソース Key、ターゲット Key、スコア境界を確認してください。

パブリッシュと動的参照

メソッド	説明
`publish(topic, message, scope=None)`	Scope プレフィックス付きの Topic にメッセージをパブリッシュする
`ref(key, scope=None, default=None)`	動的な値の取得をサポートする `DFF.API` パラメータの遅延参照を作成する

ref(...) で scope を省略すると、専用の REF Scope が使用されます。String、List、Hash、Set、ZSet はそれぞれ対応する読み取り操作で参照を解決します。参照は DFF.API の delayed_cron_job、timeout、expires、queue パラメータにのみ使用されます。

例

一般的なデータ構造
import json

DFF.CACHE.set('count', 1, expires=60, scope='job')
count = int(DFF.CACHE.get('count', scope='job') or 0)

DFF.CACHE.hmset('user:001', {'name': 'Tom', 'age': 20}, scope='users')
age = int(DFF.CACHE.hget('user:001', 'age', scope='users') or 0)

DFF.CACHE.rpush('queue', json.dumps({'id': 1}), scope='jobs')
item = json.loads(DFF.CACHE.lpop('queue', scope='jobs'))

使用上の注意

ブロッキング操作には適切な timeout を設定し、Func のタイムアウトを避けてください。
delete_pattern(...) を実行する前に、keys(...) を使用して一致する項目を確認してください。
超大な Hash に対して hstrlenall(...) を呼び出すのは避け、共有キャッシュサービスのブロックを防いでください。
publish(...) の Topic には Scope プレフィックスが付きます。購読側は一貫した Scope の規約を使用する必要があります。
複数の Script がデータを共有する場合は、明示的に scope を渡してください。

スクリプト開発 / 簡易キャッシュ DFF.CACHE