API ドキュメント

このドキュメントでは、Peewee の API を説明します。

データベース

class Database(database[, thread_safe=True[, field_types=None[, operations=None[, autoconnect=True[, **kwargs]]]]])

パラメーター

• database (str) – SQLite のデータベース名またはファイル名（None を指定して初期化を延期することもできます。その場合は、Database.init() を呼び出してデータベース名を指定する必要があります）。

• thread_safe (bool) – スレッドローカルに接続状態を保存するかどうか。

• field_types (dict) – サポートする追加のフィールドタイプのマッピング。

• operations (dict) – サポートする追加の操作のマッピング。

• autoconnect (bool) – クローズされたデータベースでクエリの実行を試行した場合に、自動的にデータベースに接続するかどうか。

• kwargs – 接続が作成されたときにデータベースドライバに渡される任意のキーワード引数。たとえば、password、host など。

Database は、以下の役割を担います。

• クエリの実行

• 接続の管理

• トランザクション処理

• イントロスペクション（内部構造の調査）

注記

データベース名は、実行時まで不明な場合は、None を指定してデータベースインスタンスを生成できます。これにより、データベースインスタンスを作成し、設定が判明した時点で別途設定できます。これは遅延初期化と呼ばれます。

例

# Sqlite database using WAL-mode and 32MB page-cache.
db = SqliteDatabase('app.db', pragmas={
    'journal_mode': 'wal',
    'cache_size': -32 * 1000})

# Postgresql database on remote host.
db = PostgresqlDatabase('my_app', user='postgres', host='10.1.0.3',
                        password='secret')

遅延初期化の例

db = PostgresqlDatabase(None)

class BaseModel(Model):
    class Meta:
        database = db

# Read database connection info from env, for example:
db_name = os.environ['DATABASE']
db_host = os.environ['PGHOST']

# Initialize database.
db.init(db_name, host=db_host, user='postgres')

param = '?'

SQLクエリにおけるパラメータプレースホルダとして使用される文字列。

quote = '"'

テーブル名やカラム名などのエンティティを表す際に使用する引用符の種類。

init(database[, **kwargs])

パラメーター

• database (str) – データベース名、またはSQLiteの場合はファイル名。

• kwargs – 接続が作成されたときにデータベースドライバに渡される任意のキーワード引数。たとえば、password、host など。

遅延データベースを初期化します。実行時データベース設定 を参照してください。

__enter__()

Database インスタンスはコンテキストマネージャとして使用できます。この場合、ラップされたブロックの期間中は接続が開いたままになります。

さらに、ラップされたブロック内で実行されるSQLは、トランザクション内で実行されます。

connection_context()

ラップされたブロックの期間中、接続を開いたままにするコンテキストマネージャを作成します。

例

def on_app_startup():
    # When app starts up, create the database tables, being sure
    # the connection is closed upon completion.
    with database.connection_context():
        database.create_tables(APP_MODELS)

connect([reuse_if_open=False])

パラメーター

reuse_if_open (bool) – 接続が既に開いている場合、例外を発生させません。

戻り値

新しい接続が開かれたかどうか。

戻り値の型

bool

例外

接続が既に開いていて、reuse_if_open が True に設定されていない場合、OperationalError を発生させます。

データベースへの接続を開きます。

close()

戻り値

接続が閉じられたかどうか。データベースが既に閉じられている場合、False を返します。

戻り値の型

bool

データベースへの接続を閉じます。

is_closed()

戻り値

データベースが閉じられている場合はTrue、開いている場合はFalseを返します。

戻り値の型

bool

connection()

開いている接続を返します。接続が開いていない場合は、接続を開きます。接続は、基盤となるデータベースドライバがデータベース接続をカプセル化するために使用するものです。

cursor([named_cursor=None])

パラメーター

named_cursor – 内部使用用。

現在の接続でcursorオブジェクトを返します。接続が開いていない場合は、接続を開きます。カーソルは、基盤となるデータベースドライバがデータベースカーソルをカプセル化するために使用するものです。

execute_sql(sql[, params=None])

パラメーター

• sql (str) – 実行するSQL文字列。

• params (tuple) – クエリのパラメータ。

戻り値

カーソルオブジェクト。

SQLクエリを実行し、結果に対するカーソルを返します。

execute(query[, **context_options])

パラメーター

• query – Query インスタンス。

• context_options – SQLジェネレータに渡す任意のオプション。

戻り値

カーソルオブジェクト。

Query インスタンスをコンパイルし、結果のSQLを実行することにより、SQLクエリを実行します。

last_insert_id(cursor[, query_type=None])

パラメーター

cursor – カーソルオブジェクト。

戻り値

最後に挿入された行の主キー。

rows_affected(cursor)

パラメーター

cursor – カーソルオブジェクト。

戻り値

クエリによって変更された行数。

in_transaction()

戻り値

トランザクションが現在開いているかどうか。

戻り値の型

bool

atomic([...])

ラップされたブロック内のクエリをトランザクション（またはブロックがネストされている場合はセーブポイント）で実行するコンテキストマネージャを作成します。

atomic() の呼び出しはネストできます。

atomic() はデコレータとしても使用できます。

データベース固有のパラメータ

PostgresqlDatabase と MySQLDatabase は isolation_level パラメータを受け付けます。SqliteDatabase は lock_type パラメータを受け付けます。

パラメーター

• isolation_level (str) – 隔離戦略: SERIALIZABLE、READ COMMITTED、REPEATABLE READ、READ UNCOMMITTED

• lock_type (str) – ロッキング戦略: DEFERRED、IMMEDIATE、EXCLUSIVE。

コード例

with db.atomic() as txn:
    perform_operation()

    with db.atomic() as nested_txn:
        perform_another_operation()

トランザクションとセーブポイントは、ラップされたブロック内で明示的にコミットまたはロールバックできます。これが発生した場合、コミット/ロールバック後に新しいトランザクションまたはセーブポイントが開始されます。

例

with db.atomic() as txn:
    User.create(username='mickey')
    txn.commit()  # Changes are saved and a new transaction begins.

    User.create(username='huey')
    txn.rollback()  # "huey" will not be saved.

    User.create(username='zaizee')

# Print the usernames of all users.
print([u.username for u in User.select()])

# Prints ["mickey", "zaizee"]

manual_commit()

ラップされたブロックの期間中、すべてのトランザクション管理を無効にするコンテキストマネージャを作成します。

例

with db.manual_commit():
    db.begin()  # Begin transaction explicitly.
    try:
        user.delete_instance(recursive=True)
    except:
        db.rollback()  # Rollback -- an error occurred.
        raise
    else:
        try:
            db.commit()  # Attempt to commit changes.
        except:
            db.rollback()  # Error committing, rollback.
            raise

上記のコードは、以下のコードと同等です。

with db.atomic():
    user.delete_instance(recursive=True)

session_start()

新しいトランザクションを開始します（コンテキストマネージャまたはデコレータを使用せずに）。このメソッドは、トランザクション内で一連の操作を実行する予定だが、デコレータまたはコンテキストマネージャを使用することが適切でない場合に役立ちます。

注記

トランザクション/セーブポイントの管理には、可能な限りDatabase.atomic()メソッドを使用することを強くお勧めします。atomicメソッドはネストを正しく管理し、適切な構成（トランザクションとセーブポイント）を使用し、常に自身の後片付けを行います。

session_start()メソッドは、一連の操作がコンテキストマネージャまたはデコレータを使用したラップに容易に適さない場合にのみ使用する必要があります。

警告

session_start メソッドを呼び出した後には、必ずsession_commit() または session_rollback() を呼び出す必要があります。

session_commit()

session_start()で開始されたトランザクション中に加えられた変更をコミットします。

session_rollback()

session_start()で開始されたトランザクション中に加えられた変更をロールバックします。

transaction([...])

ラップされたブロック内のすべてのクエリをトランザクション内で実行するコンテキストマネージャーを作成します。

データベース固有のパラメータ

PostgresqlDatabase と MySQLDatabase は isolation_level パラメータを受け付けます。SqliteDatabase は lock_type パラメータを受け付けます。

パラメーター

• isolation_level (str) – 隔離戦略: SERIALIZABLE、READ COMMITTED、REPEATABLE READ、READ UNCOMMITTED

• lock_type (str) – ロッキング戦略: DEFERRED、IMMEDIATE、EXCLUSIVE。

警告

transactionへの呼び出しはネストできません。最上位の呼び出しのみが有効になります。ネストされたトランザクションコンテキストマネージャーのロールバックまたはコミットは、未定義の動作になります。

savepoint()

ラップされたブロック内のすべてのクエリをセーブポイント内で実行するコンテキストマネージャーを作成します。セーブポイントは任意にネストできます。

警告

savepointへの呼び出しは、トランザクション内で行う必要があります。

begin()

手動コミットモードを使用する場合にトランザクションを開始します。

注記

このメソッドは、manual_commit()コンテキストマネージャーと併用してのみ使用する必要があります。

commit()

現在アクティブなトランザクションを手動でコミットします。

注記

このメソッドは、manual_commit()コンテキストマネージャーと併用してのみ使用する必要があります。

rollback()

現在アクティブなトランザクションを手動でロールバックします。

注記

このメソッドは、manual_commit()コンテキストマネージャーと併用してのみ使用する必要があります。

batch_commit(it, n)

パラメーター

• it (iterable) – 要素が生成されるイテラブルオブジェクト。

• n (int) – n個の要素ごとにコミットします。

戻り値

n個の要素のグループがトランザクション内で生成されるという点を除いて、提供されたものと同等のイテラブルオブジェクト。

このメソッドの目的は、挿入、更新などの大規模な操作のバッチ処理を簡素化することです。イテラブルオブジェクトとバッチあたりの要素数を渡すと、各バッチをトランザクションでラップする同等のイテレータによって要素が返されます。

例

# Some list or iterable containing data to insert.
row_data = [{'username': 'u1'}, {'username': 'u2'}, ...]

# Insert all data, committing every 100 rows. If, for example,
# there are 789 items in the list, then there will be a total of
# 8 transactions (7x100 and 1x89).
for row in db.batch_commit(row_data, 100):
    User.create(**row)

より効率的な代替手段として、データを複数値のINSERT文にバッチ処理することができます（たとえば、Model.insert_many()を使用）。

with db.atomic():
    for idx in range(0, len(row_data), 100):
        # Insert 100 rows at a time.
        rows = row_data[idx:idx + 100]
        User.insert_many(rows).execute()

table_exists(table[, schema=None])

パラメーター

• table (str) – テーブル名。

• schema (str) – スキーマ名（オプション）。

戻り値

テーブルが存在するかどうかを示すbool値。

get_tables([schema=None])

パラメーター

schema (str) – スキーマ名（オプション）。

戻り値

データベース内のテーブル名のリスト。

get_indexes(table[, schema=None])

パラメーター

• table (str) – テーブル名。

• schema (str) – スキーマ名（オプション）。

IndexMetadataタプルのリストを返します。

例

print(db.get_indexes('entry'))
[IndexMetadata(
     name='entry_public_list',
     sql='CREATE INDEX "entry_public_list" ...',
     columns=['timestamp'],
     unique=False,
     table='entry'),
 IndexMetadata(
     name='entry_slug',
     sql='CREATE UNIQUE INDEX "entry_slug" ON "entry" ("slug")',
     columns=['slug'],
     unique=True,
     table='entry')]

get_columns(table[, schema=None])

パラメーター

• table (str) – テーブル名。

• schema (str) – スキーマ名（オプション）。

ColumnMetadataタプルのリストを返します。

例

print(db.get_columns('entry'))
[ColumnMetadata(
     name='id',
     data_type='INTEGER',
     null=False,
     primary_key=True,
     table='entry'),
 ColumnMetadata(
     name='title',
     data_type='TEXT',
     null=False,
     primary_key=False,
     table='entry'),
 ...]

get_primary_keys(table[, schema=None])

パラメーター

• table (str) – テーブル名。

• schema (str) – スキーマ名（オプション）。

主キーを構成する列名のリストを返します。

例

print(db.get_primary_keys('entry'))
['id']

get_foreign_keys(table[, schema=None])

パラメーター

• table (str) – テーブル名。

• schema (str) – スキーマ名（オプション）。

テーブルにあるキーのForeignKeyMetadataタプルのリストを返します。

例

print(db.get_foreign_keys('entrytag'))
[ForeignKeyMetadata(
     column='entry_id',
     dest_table='entry',
     dest_column='id',
     table='entrytag'),
 ...]

get_views([schema=None])

パラメーター

schema (str) – スキーマ名（オプション）。

データベースにあるVIEWのViewMetadataタプルのリストを返します。

例

print(db.get_views())
[ViewMetadata(
     name='entries_public',
     sql='CREATE VIEW entries_public AS SELECT ... '),
 ...]

sequence_exists(seq)

パラメーター

seq (str) – シーケンス名。

戻り値

シーケンスが存在するかどうか。

戻り値の型

bool

create_tables(models[, **options])

パラメーター

• models (list) – Modelクラスのリスト。

• options – Model.create_table()を呼び出す際に指定するオプション。

指定されたモデルのリストについて、テーブル、インデックス、および関連メタデータを作成します。

依存関係が解決されるため、テーブルは適切な順序で作成されます。

drop_tables(models[, **options])

パラメーター

• models (list) – Modelクラスのリスト。

• kwargs – Model.drop_table()を呼び出す際に指定するオプション。

指定されたモデルのリストについて、テーブル、インデックス、および関連メタデータを取り除きます。

依存関係が解決されるため、テーブルは適切な順序で取り除かれます。

bind(models[, bind_refs=True[, bind_backrefs=True]])

パラメーター

• models (list) – バインドする1つ以上のModelクラス。

• bind_refs (bool) – 関連モデルをバインドします。

• bind_backrefs (bool) – バックリファレンス関連モデルをバインドします。

指定されたモデルのリストと指定されたリレーションをデータベースにバインドします。

bind_ctx(models[, bind_refs=True[, bind_backrefs=True]])

パラメーター

• models (list) – データベースにバインドするモデルのリスト。

• bind_refs (bool) – 外部キーを使用して参照されるモデルをバインドします。

• bind_backrefs (bool) – 外部キーを使用して指定されたモデルを参照するモデルをバインドします。

ラップされたブロックの期間中、指定されたモデルを現在のデータベースにバインド（関連付け）するコンテキストマネージャーを作成します。

例

MODELS = (User, Account, Note)

# Bind the given models to the db for the duration of wrapped block.
def use_test_database(fn):
    @wraps(fn)
    def inner(self):
        with test_db.bind_ctx(MODELS):
            test_db.create_tables(MODELS)
            try:
                fn(self)
            finally:
                test_db.drop_tables(MODELS)
    return inner


class TestSomething(TestCase):
    @use_test_database
    def test_something(self):
        # ... models are bound to test database ...
        pass

extract_date(date_part, date_field)

パラメーター

• date_part (str) – 抽出する日付部分（例：「year」）。

• date_field (Node) – 日付/時刻を含むSQLノード（例：DateTimeField）。

戻り値

指定された日付部分を返す関数呼び出しを表すSQLノード。

日付時刻の一部を抽出するための互換性のあるインターフェースを提供します。

truncate_date(date_part, date_field)

パラメーター

• date_part (str) – 切り捨てる日付部分（例：「day」）。

• date_field (Node) – 日付/時刻を含むSQLノード（例：DateTimeField）。

戻り値

切り捨てられた日付部分を返す関数呼び出しを表すSQLノード。

指定された解像度まで日付時刻を切り捨てるための互換性のあるインターフェースを提供します。

random()

戻り値

乱数値を返す関数呼び出しを表すSQLノード。

データベースによって提供される適切な乱数生成関数を呼び出すための互換性のあるインターフェース。PostgresとSqliteではfn.random()と等価で、MySQLではfn.rand()と等価です。

class SqliteDatabase(database[, pragmas=None[, timeout=5[, returning_clause=None[, **kwargs]]]])

パラメーター

• pragmas – 接続がオープンされるたびに設定するpragmaのキーと値を含む辞書、または2要素タプルのリスト。

• timeout – SQLiteドライバのビジータイムアウト（秒単位）を設定します。

• returning_clause (bool) – 一括INSERTクエリに対して自動的に`RETURNING`句を使用します（Sqlite 3.35以降が必要です）。

Sqliteデータベース実装です。Sqliteのみが提供する高度な機能を提供するSqliteDatabase。

• カスタム集計関数、照合順序、関数などを登録します。

• C拡張機能をロードします。

• 高度なトランザクション（ロックの種類の指定）

• さらに高度な機能については、SqliteExtDatabaseを参照してください。

データベースの初期化とPRAGMAの設定例

db = SqliteDatabase('my_app.db', pragmas=(
    ('cache_size', -16000),  # 16MB
    ('journal_mode', 'wal'),  # Use write-ahead-log journal mode.
))

# Alternatively, pragmas can be specified using a dictionary.
db = SqliteDatabase('my_app.db', pragmas={'journal_mode': 'wal'})

pragma(key[, value=SENTINEL[, permanent=False]])

パラメーター

• key – 設定名。

• value – 設定の新しい値（オプション）。

• permanent – 接続がオープンされるたびにこのpragmaを適用します。

アクティブな接続に対してPRAGMAクエリを一度実行します。値を指定しない場合、現在の値が返されます。

permanentが指定されている場合、新しい接続が開かれるたびにPRAGMAクエリも実行され、常に有効になります。

注記

デフォルトでは、現在の接続のみに影響します。実行されるPRAGMAが永続的でない場合は、後続の接続でpragmaが設定されるように、permanent=Trueを指定する必要があります。

cache_size

現在の接続のcache_size pragmaを取得または設定します。

foreign_keys

現在の接続のforeign_keys pragmaを取得または設定します。

journal_mode

journal_mode pragmaを取得または設定します。

journal_size_limit

journal_size_limit pragmaを取得または設定します。

mmap_size

現在の接続のmmap_size pragmaを取得または設定します。

page_size

page_size pragmaを取得または設定します。

read_uncommitted

現在の接続のread_uncommitted pragmaを取得または設定します。

synchronous

現在の接続のsynchronous pragmaを取得または設定します。

wal_autocheckpoint

現在の接続のwal_autocheckpoint pragmaを取得または設定します。

timeout

ビジータイムアウト（秒）を取得または設定します。

register_aggregate(klass[, name=None[, num_params=-1]])

パラメーター

• klass – 集計APIを実装するクラス。

• name (str) – 集計関数の名前（クラス名にデフォルト）。

• num_params (int) – 集計関数が受け付けるパラメータの数、または-1は任意の数。

ユーザー定義の集計関数を登録します。

新しい接続が開かれるたびに、関数が登録されます。さらに、接続が既に開いている場合、開いている接続に集計関数が登録されます。

aggregate([name=None[, num_params=-1]])

パラメーター

• name (str) – 集計関数の名前（クラス名にデフォルト）。

• num_params (int) – 集計関数が受け付けるパラメータの数、または-1は任意の数。

ユーザー定義の集計関数を登録するためのクラスデコレータ。

例

@db.aggregate('md5')
class MD5(object):
    def initialize(self):
        self.md5 = hashlib.md5()

    def step(self, value):
        self.md5.update(value)

    def finalize(self):
        return self.md5.hexdigest()


@db.aggregate()
class Product(object):
    '''Like SUM() except calculates cumulative product.'''
    def __init__(self):
        self.product = 1

    def step(self, value):
        self.product *= value

    def finalize(self):
        return self.product

register_collation(fn[, name=None])

パラメーター

• fn – 照合順序関数。

• name (str) – 照合順序の名前（関数名にデフォルト）。

ユーザー定義の照合順序を登録します。新しい接続が開かれるたびに、照合順序が登録されます。さらに、接続が既に開いている場合、開いている接続に照合順序が登録されます。

collation([name=None])

パラメーター

name (str) – 照合順序の名前（関数名にデフォルト）。

ユーザー定義の照合順序を登録するためのデコレータ。

例

@db.collation('reverse')
def collate_reverse(s1, s2):
    return -cmp(s1, s2)

# Usage:
Book.select().order_by(collate_reverse.collation(Book.title))

# Equivalent:
Book.select().order_by(Book.title.asc(collation='reverse'))

元のcollate_reverse関数には、collationという特別な属性が付いていることに気づかれたかもしれません。この追加属性により、カスタム照合順序を使用するために必要なSQLを生成する簡単な方法が提供されます。

register_function(fn[, name=None[, num_params=-1[, deterministic=None]]])

パラメーター

• fn – ユーザー定義のスカラー関数。

• name (str) – 関数の名前（関数名にデフォルト）。

• num_params (int) – 関数が受け付ける引数の数、または-1は任意の数。

• deterministic (bool) – 指定された入力に対して関数が決定論的であるかどうか（インデックスで関数を使用するにはこれが必要です）。Sqlite 3.20以降、およびsqlite3ドライバのサポートが必要です（Python 3.8のstdlibに追加）。

ユーザー定義のスカラー関数を登録します。新しい接続が開かれるたびに、関数が登録されます。さらに、接続が既に開いている場合、開いている接続に関数が登録されます。

func([name=None[, num_params=-1[, deterministic=None]]])

パラメーター

• name (str) – 関数の名前（関数名にデフォルト）。

• num_params (int) – 関数が受け付けるパラメータの数、または-1は任意の数。

• deterministic (bool) – 指定された入力に対して関数が決定論的であるかどうか（インデックスで関数を使用するにはこれが必要です）。Sqlite 3.20以降、およびsqlite3ドライバのサポートが必要です（Python 3.8のstdlibに追加）。

ユーザー定義のスカラー関数を登録するためのデコレータ。

例

@db.func('title_case')
def title_case(s):
    return s.title() if s else ''

# Usage:
title_case_books = Book.select(fn.title_case(Book.title))

register_window_function(klass[, name=None[, num_params=-1]])

パラメーター

• klass – ウィンドウ関数APIを実装するクラス。

• name (str) – ウィンドウ関数の名前（クラス名にデフォルト）。

• num_params (int) – 関数が受け付けるパラメータの数、または-1は任意の数。

ユーザー定義のウィンドウ関数を登録します。

注意

この機能には、SQLite >= 3.25.0 **と** pysqlite3 >= 0.2.0が必要です。

新しい接続が開かれるたびに、ウィンドウ関数が登録されます。さらに、接続が既に開いている場合、開いている接続にウィンドウ関数が登録されます。

window_function([name=None[, num_params=-1]])

パラメーター

• name (str) – ウィンドウ関数の名前（クラス名にデフォルト）。

• num_params (int) – 関数が受け付けるパラメータの数、または-1は任意の数。

ユーザー定義のウィンドウ関数を登録するためのクラスデコレータ。ウィンドウ関数は、以下のメソッドを定義する必要があります。

• step(<params>) - 行から値を受け取り、状態を更新します。

• inverse(<params>) - 指定された値に対するstep()の逆関数です。

• value() - ウィンドウ関数の現在の値を返します。

• finalize() - ウィンドウ関数の最終的な値を返します。

例

@db.window_function('my_sum')
class MySum(object):
    def __init__(self):
        self._value = 0

    def step(self, value):
        self._value += value

    def inverse(self, value):
        self._value -= value

    def value(self):
        return self._value

    def finalize(self):
        return self._value

table_function([name=None])

TableFunctionを登録するためのクラスデコレータです。テーブル関数は、単一の、スカラー値を返すのではなく、任意の数の行の表形式データを返すことができる、ユーザー定義関数です。

例

from playhouse.sqlite_ext import TableFunction

@db.table_function('series')
class Series(TableFunction):
    columns = ['value']
    params = ['start', 'stop', 'step']

    def initialize(self, start=0, stop=None, step=1):
        """
        Table-functions declare an initialize() method, which is
        called with whatever arguments the user has called the
        function with.
        """
        self.start = self.current = start
        self.stop = stop or float('Inf')
        self.step = step

    def iterate(self, idx):
        """
        Iterate is called repeatedly by the SQLite database engine
        until the required number of rows has been read **or** the
        function raises a `StopIteration` signalling no more rows
        are available.
        """
        if self.current > self.stop:
            raise StopIteration

        ret, self.current = self.current, self.current + self.step
        return (ret,)

# Usage:
cursor = db.execute_sql('SELECT * FROM series(?, ?, ?)', (0, 5, 2))
for value, in cursor:
    print(value)

# Prints:
# 0
# 2
# 4

unregister_aggregate(name)

パラメーター

name – ユーザー定義集計関数の名前。

ユーザー定義集計関数を登録解除します。

unregister_collation(name)

パラメーター

name – ユーザー定義照合順序の名前。

ユーザー定義照合順序を登録解除します。

unregister_function(name)

パラメーター

name – ユーザー定義スカラー関数の名前。

ユーザー定義スカラー関数を登録解除します。

unregister_table_function(name)

パラメーター

name – ユーザー定義テーブル関数の名前。

戻り値

関数が削除されたかどうかを示す真偽値。

ユーザー定義スカラー関数を登録解除します。

load_extension(extension_module)

指定されたC拡張機能を読み込みます。呼び出しスレッドで接続が現在開いている場合、その接続だけでなく、後続のすべての接続に対しても拡張機能が読み込まれます。

たとえば、クロージャテーブル拡張機能をコンパイルし、アプリケーションで使用したい場合は、次のように記述します。

db = SqliteExtDatabase('my_app.db')
db.load_extension('closure')

attach(filename, name)

パラメーター

• filename (str) – アタッチするデータベース（またはメモリ内データベースの場合は:memory:）。

• name (str) – アタッチされたデータベースのスキーマ名。

戻り値

成功を示すブール値。

すべてのデータベース接続にアタッチされる別のデータベースファイルを登録します。メインデータベースが現在接続されている場合、新しいデータベースは開いている接続にアタッチされます。

注記

このメソッドを使用してアタッチされたデータベースは、データベース接続が開かれるたびにアタッチされます。

detach(name)

パラメーター

name (str) – アタッチされたデータベースのスキーマ名。

戻り値

成功を示すブール値。

attach()の呼び出しで以前にアタッチされた別のデータベースファイルを登録解除します。メインデータベースが現在接続されている場合、アタッチされたデータベースは開いている接続からデタッチされます。

atomic([lock_type=None])

パラメーター

lock_type (str) – ロッキング戦略: DEFERRED、IMMEDIATE、EXCLUSIVE。

指定されたロック戦略（指定されていない場合はDEFERREDが使用されます）を使用して、アトミックなコンテキストマネージャーを作成します。

注記

ロックタイプは、最外部のatomic()ブロックのみに適用されます。

transaction([lock_type=None])

パラメーター

lock_type (str) – ロッキング戦略: DEFERRED、IMMEDIATE、EXCLUSIVE。

指定されたロック戦略（デフォルトはDEFERRED）を使用して、トランザクションコンテキストマネージャーを作成します。

class PostgresqlDatabase(database[, register_unicode=True[, encoding=None[, isolation_level=None]]])

PostgreSQLデータベースの実装。

追加のオプションキーワードパラメーター

パラメーター

• register_unicode (bool) – Unicode型の登録。

• encoding (str) – データベースエンコーディング。

• isolation_level (int) – psycopg2.extensionsモジュールで定義されている分離レベル定数。

set_time_zone(timezone)

パラメーター

timezone (str) – タイムゾーン名（例：「US/Central」）。

戻り値

戻り値なし。

現在の接続でタイムゾーンを設定します。接続が開いていない場合は、接続が開きます。

atomic([isolation_level=None])

パラメーター

isolation_level (str) – 隔離戦略: SERIALIZABLE、READ COMMITTED、REPEATABLE READ、READ UNCOMMITTED

指定された分離レベル（指定されていない場合はサーバーのデフォルトが使用されます）を使用して、アトミックなコンテキストマネージャーを作成します。

注記

分離レベルは、最外部のatomic()ブロックのみに適用されます。

transaction([isolation_level=None])

パラメーター

isolation_level (str) – 隔離戦略: SERIALIZABLE、READ COMMITTED、REPEATABLE READ、READ UNCOMMITTED

指定された分離レベル（指定されていない場合はサーバーのデフォルトが使用されます）を使用して、トランザクションコンテキストマネージャーを作成します。

class MySQLDatabase(database[, **kwargs])

MySQLデータベースの実装。

atomic([isolation_level=None])

パラメーター

isolation_level (str) – 隔離戦略: SERIALIZABLE、READ COMMITTED、REPEATABLE READ、READ UNCOMMITTED

指定された分離レベル（指定されていない場合はサーバーのデフォルトが使用されます）を使用して、アトミックなコンテキストマネージャーを作成します。

注記

分離レベルは、最外部のatomic()ブロックのみに適用されます。

transaction([isolation_level=None])

パラメーター

isolation_level (str) – 隔離戦略: SERIALIZABLE、READ COMMITTED、REPEATABLE READ、READ UNCOMMITTED

指定された分離レベル（指定されていない場合はサーバーのデフォルトが使用されます）を使用して、トランザクションコンテキストマネージャーを作成します。

クエリビルダー

class Node

SQLクエリのASTを構成するすべてのコンポーネントの基本クラスです。

static copy(method)

ノードの状態を変更するNodeメソッドで使用するためのデコレータです。これにより、メソッドチェーンが可能になります。

query = MyModel.select()
new_query = query.where(MyModel.field == 'value')

unwrap()

「ラップされた」ノードを再帰的にアンラップするためのAPIです。基本ケースはselfを返すことです。

is_alias()

ノードが、ある時点でユーザーによって明示的にエイリアスされているかどうかを判断するためのAPIです。

class Source([alias=None])

行タプルのソース（例：テーブル、結合、またはSELECTクエリ）。デフォルトでは、「c」という名前の「マジック」属性を提供し、これは列/属性ルックアップのファクトリです。

User = Table('users')
query = (User
         .select(User.c.username)
         .where(User.c.active == True)
         .order_by(User.c.username))

alias(name)

指定されたエイリアスを適用してオブジェクトのコピーを返します。

select(*columns)

パラメーター

columns – Columnインスタンス、式、関数、サブクエリ、または選択したいその他のもの。

テーブルでSelectクエリを作成します。テーブルが列を明示的に宣言し、列が提供されない場合、デフォルトではテーブルで定義されたすべての列が選択されます。

join(dest[, join_type='INNER'[, on=None]])

パラメーター

• dest (Source) – 指定された宛先とテーブルを結合します。

• join_type (str) – 結合の種類。

• on – 結合述語として使用する式。

戻り値

Joinインスタンス。

結合の種類は次のいずれかです。

• JOIN.INNER

• JOIN.LEFT_OUTER

• JOIN.RIGHT_OUTER

• JOIN.FULL

• JOIN.FULL_OUTER

• JOIN.CROSS

left_outer_join(dest[, on=None])

パラメーター

• dest (Source) – 指定された宛先とテーブルを結合します。

• on – 結合述語として使用する式。

戻り値

Joinインスタンス。

LEFT OUTER結合を使用してjoin()を呼び出すための便利なメソッドです。

class BaseTable

演算子オーバーロードを介してJOINをサポートする、テーブルのようなオブジェクトの基本クラスです。

__and__(dest)

destに対してINNER JOINを実行します。

__add__(dest)

destに対してLEFT OUTER JOINを実行します。

__sub__(dest)

destに対してRIGHT OUTER JOINを実行します。

__or__(dest)

destに対してFULL OUTER JOINを実行します。

__mul__(dest)

destに対してCROSS JOINを実行します。

class Table(name[, columns=None[, primary_key=None[, schema=None[, alias=None]]]])

データベース内のテーブル（またはビューなどのテーブルのようなオブジェクト）を表します。

パラメーター

• name (str) – データベーステーブル名

• columns (tuple) – 列名リスト（オプション）。

• primary_key (str) – 主キー列の名前。

• schema (str) – テーブルにアクセスするために使用されるスキーマ名（必要に応じて）。

• alias (str) – SQLクエリでテーブルに使用されるエイリアス。

注記

列が指定されている場合、マジック属性「c」は無効になります。

列が明示的に定義されていない場合、テーブルには、テーブル列に動的にアクセスできるファクトリである特別な属性「c」があります。

例

User = Table('users')
query = (User
         .select(User.c.id, User.c.username)
         .order_by(User.c.username))

列が指定されている場合の同等の例

User = Table('users', ('id', 'username'))
query = (User
         .select(User.id, User.username)
         .order_by(User.username))

bind([database=None])

パラメーター

database – Database オブジェクト。

このテーブルを指定されたデータベースにバインドします（空のままにしてバインド解除することもできます）。

テーブルがデータベースにバインドされている場合、クエリのexecuteメソッドでデータベースを指定する必要なく、クエリを実行できます。

bind_ctx([database=None])

パラメーター

database – Database オブジェクト。

ラップされたブロックの期間、テーブルを指定されたデータベースにバインドするコンテキストマネージャーを返します。

select(*columns)

パラメーター

columns – Columnインスタンス、式、関数、サブクエリ、または選択したいその他のもの。

テーブルでSelectクエリを作成します。テーブルが列を明示的に宣言し、列が提供されない場合、デフォルトではテーブルで定義されたすべての列が選択されます。

例

User = Table('users', ('id', 'username'))

# Because columns were defined on the Table, we will default to
# selecting both of the User table's columns.
# Evaluates to SELECT id, username FROM users
query = User.select()

Note = Table('notes')
query = (Note
         .select(Note.c.content, Note.c.timestamp, User.username)
         .join(User, on=(Note.c.user_id == User.id))
         .where(Note.c.is_published == True)
         .order_by(Note.c.timestamp.desc()))

# Using a function to select users and the number of notes they
# have authored.
query = (User
         .select(
            User.username,
            fn.COUNT(Note.c.id).alias('n_notes'))
         .join(
            Note,
            JOIN.LEFT_OUTER,
            on=(User.id == Note.c.user_id))
         .order_by(fn.COUNT(Note.c.id).desc()))

insert([insert=None[, columns=None[, **kwargs]]])

パラメーター

• insert – 列と値のマッピングを表す辞書、辞書を生成する反復可能オブジェクト（つまりリスト）、またはSelectクエリ。

• columns (list) – 挿入されるデータが辞書ではない場合に挿入する列のリスト。

• kwargs – 列名と値のマッピング。

テーブルへのInsertクエリを作成します。

replace([insert=None[, columns=None[, **kwargs]]])

パラメーター

• insert – 列と値のマッピングを表す辞書、辞書を生成する反復可能オブジェクト（つまりリスト）、またはSelectクエリ。

• columns (list) – 挿入されるデータが辞書ではない場合に挿入する列のリスト。

• kwargs – 列名と値のマッピング。

競合解決方法が置換であるテーブルへのInsertクエリを作成します。

update([update=None[, **kwargs]])

パラメーター

• update – 列と値のマッピングを表す辞書。

• kwargs – 列名と値のマッピング。

テーブルのUpdateクエリを作成します。

delete()

テーブルのDeleteクエリを作成します。

class Join(lhs, rhs[, join_type=JOIN.INNER[, on=None[, alias=None]]])

2つのテーブルのようなオブジェクト間のJOINを表します。

パラメーター

• lhs – JOINの左側。

• rhs – JOINの右側。

• join_type – JOINの種類。例：JOIN.INNER、JOIN.LEFT_OUTERなど。

• on – JOIN述語を記述する式。

• alias (str) – 結合されたデータに適用するエイリアス。

on(predicate)

パラメーター

predicate (Expression) – JOIN述語。

このJOINで使用される述語式を指定します。

class ValuesList(values[, columns=None[, alias=None]])

テーブルのように使用できる値リストを表します。

パラメーター

• values – 表す行データを含むリストのリスト。

• columns (list) – 各行の列に付ける名前。

• alias (str) – 値リストに使用するエイリアス。

例

data = [(1, 'first'), (2, 'second')]
vl = ValuesList(data, columns=('idx', 'name'))

query = (vl
         .select(vl.c.idx, vl.c.name)
         .order_by(vl.c.idx))
# Yields:
# SELECT t1.idx, t1.name
# FROM (VALUES (1, 'first'), (2, 'second')) AS t1(idx, name)
# ORDER BY t1.idx

columns(*names)

パラメーター

names – データの列に適用する名前。

例

vl = ValuesList([(1, 'first'), (2, 'second')])
vl = vl.columns('idx', 'name').alias('v')

query = vl.select(vl.c.idx, vl.c.name)
# Yields:
# SELECT v.idx, v.name
# FROM (VALUES (1, 'first'), (2, 'second')) AS v(idx, name)

class CTE(name, query[, recursive=False[, columns=None]])

共通テーブル式を表します。クエリの例については、共通テーブル式を参照してください。

パラメーター

• name – CTEの名前。

• query – CTEを記述するSelectクエリ。

• recursive (bool) – CTEが再帰的かどうか。

• columns (list) – CTEによって生成される列の明示的なリスト（オプション）。

select_from(*columns)

指定された共通テーブル式を新しいクエリのソースとして使用するSELECTクエリを作成します。

パラメーター

columns – CTEから選択する1つ以上の列。

戻り値

共通テーブル式を利用したSelectクエリ

union_all(other)

基本ケースのCTEで使用され、CTEの再帰項を構築します。

パラメーター

other – 再帰項。通常はSelectクエリ。

戻り値

指定された再帰項を持つ再帰的なCTE。

class ColumnBase

列のようなオブジェクト、属性、または式の基本クラスです。

列のようなオブジェクトは、さまざまな演算子と特殊メソッドを使用して構成できます。

• &: 論理積 (AND)

• |: 論理和 (OR)

• +: 加算

• -: 減算

• *: 乗算

• /: 除算

• ^: 排他的論理和 (XOR)

• ==: 等価

• !=: 不等価

• >: より大きい

• <: より小さい

• >=: 以上

• <=: 以下

• <<: IN

• >>: IS (例: IS NULL)

• %: LIKE

• **: ILIKE (大文字小文字を区別しないLIKE)

• bin_and(): バイナリAND

• bin_or(): バイナリOR

• in_(): IN

• not_in(): NOT IN

• regexp(): REGEXP (正規表現)

• is_null(True/False): IS NULL または IS NOT NULL

• contains(s): LIKE %s% (sを含む)

• startswith(s): LIKE s% (sで始まる)

• endswith(s): LIKE %s (sで終わる)

• between(low, high): BETWEEN low AND high (low以上high以下)

• concat(): || (連結)

alias(alias)

パラメーター

**alias** (str) – 指定された列状オブジェクトのエイリアス。

戻り値

Alias オブジェクト。

指定された列状オブジェクトに与えるべきエイリアスを指定します。

cast(as_type)

パラメーター

**as_type** (str) – キャスト先の型名。

戻り値

Cast オブジェクト。

CAST式を作成します。

asc([collation=None[, nulls=None]])

パラメーター

• **collation** (str) – 並べ替えに使用する照合順序名。

• **nulls** (str) – NULL値のソート順序 (FIRST または LAST)。

戻り値

列に対する昇順のOrdering オブジェクト。

desc([collation=None[, nulls=None]])

パラメーター

• **collation** (str) – 並べ替えに使用する照合順序名。

• **nulls** (str) – NULL値のソート順序 (FIRST または LAST)。

戻り値

列に対する降順のOrdering オブジェクト。

__invert__()

戻り値

列に対するNegated ラッパー。

class Column(source, name)

パラメーター

• **source** (Source) – 列のソース。

• **name** (str) – 列名。

テーブル上の列、またはサブクエリによって返される列。

class Alias(node, alias)

パラメーター

• **node** (Node) – 列状オブジェクト。

• **alias** (str) – 列に割り当てるエイリアス。

指定された列状オブジェクトの命名されたエイリアスを作成します。

alias([alias=None])

パラメーター

**alias** (str) – エイリアスされた列の新しい名前 (または None)。

エイリアスされた列状オブジェクトの新しいAlias を作成します。新しいエイリアスがNoneの場合、元の列状オブジェクトが返されます。

class Negated(node)

否定された列状オブジェクトを表します。

class Value(value[, converterNone[, unpack=True]])

パラメーター

• **value** – Pythonオブジェクトまたはスカラー値。

• **converter** – 値をデータベースが理解できる型に変換するために使用される関数。

• **unpack** (bool) – リストまたはタプルを値のリストに展開するか、そのまま扱うか。

パラメーター化されたクエリで使用される値。渡された値がデータベースドライバが理解できる型に適応できることを保証するのは呼び出し元の責任です。

AsIs(value)

そのまま扱われ、データベースドライバに直接渡されるValue を表します。これは、ネイティブのPythonデータ型を受け入れるデータベース拡張機能を使用しており、Peeweeが値の処理を課さないようにしたい場合に役立つ場合があります。

class Cast(node, cast)

パラメーター

• **node** – 列状オブジェクト。

• **cast** (str) – キャスト先の型。

CAST(<node> AS <cast>)式を表します。

class Ordering(node, direction[, collation=None[, nulls=None]])

パラメーター

• **node** – 列状オブジェクト。

• **direction** (str) – ASC または DESC

• **collation** (str) – 並べ替えに使用する照合順序名。

• **nulls** (str) – NULL値のソート順序 (FIRST または LAST)。

列状オブジェクトによるソート順序を表します。

PostgreSQLは非標準句（「NULLS FIRST/LAST」）をサポートしています。Peeweeは、これをサポートしていないデータベース（Sqlite/MySQL）に対しては、自動的に同等のCASEステートメントを使用します。

collate([collation=None])

パラメーター

**collation** (str) – 並べ替えに使用する照合順序名。

Asc(node[, collation=None[, nulls=None]])

昇順のOrderingオブジェクトをインスタンス化する簡略表記です。

Desc(node[, collation=None[, nulls=None]])

降順のOrderingオブジェクトをインスタンス化する簡略表記です。

class Expression(lhs, op, rhs[, flat=True])

パラメーター

• **lhs** – 左辺。

• **op** – 演算子。

• **rhs** – 右辺。

• **flat** (bool) – 式を括弧で囲むかどうか。

(lhs op rhs) の形式の2項式を表現します。(例: (foo + 1))

class Entity(*path)

パラメーター

**path** – エンティティ名のドット区切りパスを構成する要素。

クエリ内の引用されたエンティティ（テーブル、列、エイリアスなど）を表します。名前は複数の要素で構成される場合があります（例: “a_table”.”column_name”）。

__getattr__(self, attr)

サブエンティティを作成するためのファクトリメソッドです。

class SQL(sql[, params=None])

パラメーター

• **sql** (str) – SQLクエリ文字列。

• **params** (tuple) – クエリのパラメータ（オプション）。

パラメータ化されたSQLクエリまたはクエリフラグメントを表します。

Check(constraint[, name=None])

パラメーター

• **constraint** (str) – 制約SQL。

• **name** (str) – 制約名。

CHECK制約を表します。

警告

MySQLでは、列定義と共に制約をインラインで記述する場合、nameパラメータがサポートされない場合があります。解決策としては、フィールドインスタンスのconstraints=[...]リストではなく、モデルのMeta.constraintsリストに名前付きCheck制約を配置することです。

class Function(name, arguments[, coerce=True[, python_value=None]])

パラメーター

• **name** (str) – 関数名。

• **arguments** (tuple) – 関数への引数。

• **coerce** (bool) – カーソルから関数の戻り値を読み取る際に、関数の結果を特定のデータ型に強制変換するかどうか。

• **python_value** (callable) – カーソルから返された値を変換するために使用する関数。

任意のSQL関数呼び出しを表します。

注記

このクラスを直接インスタンス化する代わりに、fnヘルパーを使用することをお勧めします。

任意のSQL関数を呼び出すためのfnの使用例

# Query users and count of tweets authored.
query = (User
         .select(User.username, fn.COUNT(Tweet.id).alias('ct'))
         .join(Tweet, JOIN.LEFT_OUTER, on=(User.id == Tweet.user_id))
         .group_by(User.username)
         .order_by(fn.COUNT(Tweet.id).desc()))

over([partition_by=None[, order_by=None[, start=None[, end=None[, window=None[, exclude=None]]]]]])

パラメーター

• **partition_by** (list) – パーティションする列のリスト。

• **order_by** (list) – ウィンドウを順序付ける列/式のリスト。

• **start** – ウィンドウ範囲の開始を表すSQLインスタンスまたは文字列。

• **end** – ウィンドウ範囲の終了を表すSQLインスタンスまたは文字列。

• **frame_type** (str) – Window.RANGE、Window.ROWS、またはWindow.GROUPS。

• **window** (Window) – Windowインスタンス。

• **exclude** – フレーム除外。 Window.CURRENT_ROW、Window.GROUP、Window.TIES、またはWindow.NO_OTHERSのいずれか。

注記

Peeweeでのウィンドウ関数の使用方法の詳細については、「ウィンドウ関数」セクションを参照してください。

例

# Using a simple partition on a single column.
query = (Sample
         .select(
            Sample.counter,
            Sample.value,
            fn.AVG(Sample.value).over([Sample.counter]))
         .order_by(Sample.counter))

# Equivalent example Using a Window() instance instead.
window = Window(partition_by=[Sample.counter])
query = (Sample
         .select(
            Sample.counter,
            Sample.value,
            fn.AVG(Sample.value).over(window))
         .window(window)  # Note call to ".window()"
         .order_by(Sample.counter))

# Example using bounded window.
query = (Sample
         .select(Sample.value,
                 fn.SUM(Sample.value).over(
                    partition_by=[Sample.counter],
                    start=Window.CURRENT_ROW,  # current row
                    end=Window.following()))  # unbounded following
         .order_by(Sample.id))

filter(where)

パラメーター

**where** – 集約をフィルタリングするための式。

集約関数にFILTER (WHERE...)句を追加します。where式は、集約関数に供給される行を決定するために評価されます。このSQL機能は、PostgresとSQLiteでサポートされています。

coerce([coerce=True])

パラメーター

**coerce** (bool) – 関数呼び出しの結果をPythonデータ型に強制変換しようとするかどうか。

coerceがTrueの場合、ターゲットデータ型はいくつかのヒューリスティックを使用して推測されます。この動作については、BaseModelCursorWrapper._initialize_columnsメソッドのソースコードを参照してください。

python_value([func=None])

パラメーター

**python_value** (callable) – カーソルから返された値を変換するために使用する関数。

データベースカーソルによって返された値を変換するために使用する特定の関数を指定します。例えば

# Get user and a list of their tweet IDs. The tweet IDs are
# returned as a comma-separated string by the db, so we'll split
# the result string and convert the values to python ints.
convert_ids = lambda s: [int(i) for i in (s or '').split(',') if i]
tweet_ids = (fn
             .GROUP_CONCAT(Tweet.id)
             .python_value(convert_ids))

query = (User
         .select(User.username, tweet_ids.alias('tweet_ids'))
         .group_by(User.username))

for user in query:
    print(user.username, user.tweet_ids)

# e.g.,
# huey [1, 4, 5, 7]
# mickey [2, 3, 6]
# zaizee []

fn()

fn()ヘルパーは実際にはFunctionのインスタンスであり、SQL関数を呼び出すための優れたAPIを提供する__getattr__フックを実装しています。

SQL関数呼び出しを表すノードを作成するには、fnの属性として関数名を使用し、Python関数を呼び出す場合と同様に引数を指定します。

# List users and the number of tweets they have authored,
# from highest-to-lowest:
sql_count = fn.COUNT(Tweet.id)
query = (User
         .select(User, sql_count.alias('count'))
         .join(Tweet, JOIN.LEFT_OUTER)
         .group_by(User)
         .order_by(sql_count.desc()))

# Get the timestamp of the most recent tweet:
query = Tweet.select(fn.MAX(Tweet.timestamp))
max_timestamp = query.scalar()  # Retrieve scalar result from query.

関数呼び出しは、他のものと同様に、合成およびネストできます。

# Get users whose username begins with "A" or "a":
a_users = User.select().where(fn.LOWER(fn.SUBSTR(User.username, 1, 1)) == 'a')

class Window([partition_by=None[, order_by=None[, start=None[, end=None[, frame_type=None[, extends=None[, exclude=None[, alias=None]]]]]]]])

パラメーター

• **partition_by** (list) – パーティションする列のリスト。

• **order_by** (list) – 並べ替え対象の列のリスト。

• **start** – ウィンドウ範囲の開始を表すSQLインスタンスまたは文字列。

• **end** – ウィンドウ範囲の終了を表すSQLインスタンスまたは文字列。

• **frame_type** (str) – Window.RANGE、Window.ROWS、またはWindow.GROUPS。

• **extends** – 拡張するWindow定義。または、ウィンドウのエイリアスを指定することもできます。

• **exclude** – フレーム除外。 Window.CURRENT_ROW、Window.GROUP、Window.TIES、またはWindow.NO_OTHERSのいずれか。

• **alias** (str) – ウィンドウのエイリアス。

WINDOW句を表します。

注記

Peeweeでのウィンドウ関数の使用方法の詳細については、「ウィンドウ関数」セクションを参照してください。

RANGE

ROWS

GROUPS

ウィンドウのframe_typeを指定します。「フレームタイプ：RANGE対ROWS対GROUPS」を参照してください。

CURRENT_ROW

開始/終了句またはフレーム除外パラメータで使用するための現在の行への参照。

NO_OTHERS

GROUP

TIES

ウィンドウフレーム除外パラメータを指定します。

static preceding([value=None])

パラメーター

value – 先行する行数。 None の場合、UNBOUNDED。

ウィンドウ範囲の start パラメータとして渡すのに適したSQLを生成するためのコンビニエンスメソッド。

static following([value=None])

パラメーター

value – 後続する行数。 None の場合、UNBOUNDED。

ウィンドウ範囲の end パラメータとして渡すのに適したSQLを生成するためのコンビニエンスメソッド。

as_rows()

as_range()

as_groups()

フレームの種類を指定します。

extends([window=None])

パラメーター

window (Window) – 拡張する Window 定義。あるいは、ウィンドウのエイリアスを指定することもできます。

exclude([frame_exclusion=None])

パラメーター

frame_exclusion – フレームの除外。 Window.CURRENT_ROW、Window.GROUP、Window.TIES、またはWindow.NO_OTHERS のいずれか。

alias([alias=None])

パラメーター

alias (str) – ウィンドウに使用するエイリアス。

Case(predicate, expression_tuples[, default=None]])

パラメーター

• predicate – CASE クエリのための述語（省略可能）。

• expression_tuples – 評価する1つ以上のケース。

• default – デフォルト値（省略可能）。

戻り値

CASE 文の表現。

例

Number = Table('numbers', ('val',))

num_as_str = Case(Number.val, (
    (1, 'one'),
    (2, 'two'),
    (3, 'three')), 'a lot')

query = Number.select(Number.val, num_as_str.alias('num_str'))

# The above is equivalent to:
# SELECT "val",
#   CASE "val"
#       WHEN 1 THEN 'one'
#       WHEN 2 THEN 'two'
#       WHEN 3 THEN 'three'
#       ELSE 'a lot' END AS "num_str"
# FROM "numbers"

num_as_str = Case(None, (
    (Number.val == 1, 'one'),
    (Number.val == 2, 'two'),
    (Number.val == 3, 'three')), 'a lot')
query = Number.select(Number.val, num_as_str.alias('num_str'))

# The above is equivalent to:
# SELECT "val",
#   CASE
#       WHEN "val" = 1 THEN 'one'
#       WHEN "val" = 2 THEN 'two'
#       WHEN "val" = 3 THEN 'three'
#       ELSE 'a lot' END AS "num_str"
# FROM "numbers"

class NodeList(nodes[, glue=' '[, parens=False]])

パラメーター

• nodes (list) – 0個以上のノード。

• glue (str) – SQLに変換するときのノードの結合方法。

• parens (bool) – 結果のSQLを括弧で囲むかどうか。

ノードのリスト、複数部分からなる句、パラメータのリストなどを表現します。

CommaNodeList(nodes)

パラメーター

nodes (list) – 0個以上のノード。

戻り値

NodeList の一種

コンマで結合されたノードのリストを表します。

EnclosedNodeList(nodes)

パラメーター

nodes (list) – 0個以上のノード。

戻り値

NodeList の一種

コンマで結合され、括弧で囲まれたノードのリストを表します。

class DQ(**query)

パラメーター

query – Djangoスタイルのルックアップを使用した任意のフィルタ式。

Model.filter() または ModelSelect.filter() メソッドで使用できる、コンポーズ可能なDjangoスタイルのフィルタ式を表します。

class Tuple(*args)

SQL の 行値 を表します。行値はほとんどのデータベースでサポートされています。

class OnConflict([action=None[, update=None[, preserve=None[, where=None[, conflict_target=None[, conflict_where=None[, conflict_constraint=None]]]]]]])

パラメーター

• action (str) – 衝突を解決する際に取るアクション。

• update – 列を新しい値にマッピングする辞書。

• preserve – 元の INSERT から値を保持する列のリスト。EXCLUDED も参照してください。

• where – 衝突解決を制限する式。

• conflict_target – 制約を構成する列。

• conflict_where – 部分インデックス（WHERE句を持つインデックス）の場合、制約ターゲットと一致させるために必要な式。

• conflict_constraint (str) – 衝突解決に使用する制約の名前。現在、Postgresのみサポート。

データ変更クエリのための衝突解決句を表します。

使用されているデータベースドライバによっては、上記の1つ以上の引数が必須になる場合があります。

preserve(*columns)

パラメーター

columns – 値を保持する列。

update([_data=None[, **kwargs]])

パラメーター

• _data (dict) – 列を新しい値にマッピングする辞書。

• kwargs – 列名と新しい値をマッピングする辞書。

update() メソッドは、列と値のマッピング辞書、または同じことを表すキーワード引数のいずれかで呼び出すことができます。

where(*expressions)

パラメーター

expressions – 衝突解決句のアクションを制限する式。

conflict_target(*constraints)

パラメーター

constraints – 衝突解決のターゲットとして使用する列。

conflict_where(*expressions)

パラメーター

expressions – 衝突ターゲットが部分インデックスの場合、衝突ターゲットインデックスと一致する式。

conflict_constraint(constraint)

パラメーター

constraint (str) – 衝突解決のターゲットとして使用する制約の名前。現在、Postgresのみサポート。

class EXCLUDED

INSERT ... ON CONFLICT と共に使用される EXCLUDED 名前空間を公開するヘルパーオブジェクト。 これは、衝突データ内の特定の列に対応する属性にアクセスすることで使用する「魔法」のヘルパーです。

例

class KV(Model):
    key = CharField(unique=True)
    value = IntegerField()

# Create one row.
KV.create(key='k1', value=1)

# Demonstrate usage of EXCLUDED.
# Here we will attempt to insert a new value for a given key. If that
# key already exists, then we will update its value with the *sum* of its
# original value and the value we attempted to insert -- provided that
# the new value is larger than the original value.
query = (KV.insert(key='k1', value=10)
         .on_conflict(conflict_target=[KV.key],
                      update={KV.value: KV.value + EXCLUDED.value},
                      where=(EXCLUDED.value > KV.value)))

# Executing the above query will result in the following data being
# present in the "kv" table:
# (key='k1', value=11)
query.execute()

# If we attempted to execute the query *again*, then nothing would be
# updated, as the new value (10) is now less than the value in the
# original row (11).

class BaseQuery

他のすべてのクエリクラスが派生する親クラスです。BaseQueryはコード内で直接扱うことはありませんが、すべてのクエリタイプで共通のいくつかのメソッドを実装しています。

default_row_type = ROW.DICT

bind([database=None])

パラメーター

database (Database) – クエリを実行するデータベース。

指定されたデータベースにクエリをバインドして実行します。

dicts([as_dict=True])

パラメーター

as_dict (bool) – 行を辞書として返すかどうかを指定します。

行を辞書として返します。

tuples([as_tuples=True])

パラメーター

as_tuple (bool) – 行をタプルとして返すかどうかを指定します。

行をタプルとして返します。

namedtuples([as_namedtuple=True])

パラメーター

as_namedtuple (bool) – 行を名前付きタプルとして返すかどうかを指定します。

行を名前付きタプルとして返します。

objects([constructor=None])

パラメーター

constructor – 行の辞書を受け取り、任意のオブジェクトを返す関数。

指定されたコンストラクタを使用して、行を任意のオブジェクトとして返します。

sql()

戻り値

クエリのSQLとパラメータからなる2要素のタプル。

execute(database)

パラメーター

database (Database) – クエリを実行するデータベース。クエリが既にデータベースにバインドされている場合は不要です。

クエリを実行し、結果を返します（実行されるクエリのタイプによって異なります）。たとえば、selectクエリでは、結果はクエリ結果のイテレータになります。

iterator([database=None])

パラメーター

database (Database) – クエリを実行するデータベース。クエリが既にデータベースにバインドされている場合は不要です。

クエリを実行し、結果セットのイテレータを返します。大規模な結果セットの場合、このメソッドは、行が反復処理中にメモリにキャッシュされないため、好ましい方法です。

注記

行はキャッシュされないため、クエリは一度だけ反復処理できます。後続の反復処理では、カーソルが消費されているため、空の結果セットが返されます。

例

query = StatTbl.select().order_by(StatTbl.timestamp).tuples()
for row in query.iterator(db):
    process_row(row)

__iter__()

クエリを実行し、結果セットのイテレータを返します。

iterator()とは異なり、このメソッドは効率的な反復処理、インデックス付け、スライスを可能にするために、行をキャッシュします。

__getitem__(value)

パラメーター

value – 整数インデックスまたはスライスのいずれか。

結果セットから行または行の範囲を取得します。

__len__()

結果セット内の行数を返します。

警告

COUNT()クエリは発行されません。代わりに、結果セットは通常の反復処理と同様にロードされ、長さは結果セットのサイズから決定されます。

class RawQuery([sql=None[, params=None[, **kwargs]]])

パラメーター

• sql (str) – SQLクエリ。

• params (tuple) – パラメータ（オプション）。

実行するSQLを直接指定してクエリを作成します。

class Query([where=None[, order_by=None[, limit=None[, offset=None[, **kwargs]]]]])

パラメーター

• where – WHERE句の表現。

• order_by (tuple) – 並べ替える列または値。

• limit (int) – LIMIT句の値。

• offset (int) – OFFSET句の値。

メソッドチェーンAPIをサポートするクエリの基底クラス。

with_cte(*cte_list)

パラメーター

cte_list – CTEオブジェクトを0個以上。

指定された共通テーブル式をクエリに含めます。以前に指定されたCTEは上書きされます。共通テーブル式の例については、共通テーブル式を参照してください。

cte(name[, recursive=False[, columns=None]])

パラメーター

• name (str) – 共通テーブル式のエイリアス。

• recursive (bool) – 再帰的なCTEになりますか？

• columns (list) – 列名のリスト（文字列として）。

クエリを共通テーブル式として使用するように指定します。たとえば、カテゴリツリーをモデル化し、親リンク外部キーを使用している場合、再帰的なCTEを使用してすべてのカテゴリとその絶対深さを取得できます。

class Category(Model):
    name = TextField()
    parent = ForeignKeyField('self', backref='children', null=True)

# The base case of our recursive CTE will be categories that are at
# the root level -- in other words, categories without parents.
roots = (Category
         .select(Category.name, Value(0).alias('level'))
         .where(Category.parent.is_null())
         .cte(name='roots', recursive=True))

# The recursive term will select the category name and increment
# the depth, joining on the base term so that the recursive term
# consists of all children of the base category.
RTerm = Category.alias()
recursive = (RTerm
             .select(RTerm.name, (roots.c.level + 1).alias('level'))
             .join(roots, on=(RTerm.parent == roots.c.id)))

# Express <base term> UNION ALL <recursive term>.
cte = roots.union_all(recursive)

# Select name and level from the recursive CTE.
query = (cte
         .select_from(cte.c.name, cte.c.level)
         .order_by(cte.c.name))

for category in query:
    print(category.name, category.level)

CTEの詳細は、共通テーブル式を参照してください。

where(*expressions)

パラメーター

expressions – WHERE句に含める式を0個以上。

指定された式をクエリのWHERE句に含めます。これらの式は、以前に指定されたWHERE式とANDで結合されます。

ユーザー名が「somebody」であるユーザーを選択する例

sq = User.select().where(User.username == 'somebody')

編集者または管理者のいずれかであるユーザーが作成したツイートを選択する例

sq = Tweet.select().join(User).where(
    (User.is_editor == True) |
    (User.is_admin == True))

もはやアクティブでないユーザーによるツイートを削除する例

inactive_users = User.select().where(User.active == False)
dq = (Tweet
      .delete()
      .where(Tweet.user.in_(inactive_users)))
dq.execute()  # Return number of tweets deleted.

注記

where()呼び出しはチェーン可能です。複数の呼び出しは「AND」で結合されます。

orwhere(*expressions)

パラメーター

expressions – WHERE句に含める式を0個以上。

指定された式をクエリのWHERE句に含めます。このメソッドはQuery.where()メソッドと同じですが、式は以前に指定されたWHERE式とORで結合されます。

order_by(*values)

パラメーター

values – 並べ替えるColumnのようなオブジェクトを0個以上。

ORDER BY句を定義します。以前に指定された値は上書きされます。

order_by_extend(*values)

パラメーター

values – 並べ替えるColumnのようなオブジェクトを0個以上。

以前に指定されたORDER BY句を指定された値で拡張します。

limit([value=None])

パラメーター

value (int) – LIMIT句の値を指定します。

offset([value=None])

パラメーター

value (int) – OFFSET句の値を指定します。

paginate(page[, paginate_by=20])

パラメーター

• page (int) – 結果のページ番号（1から開始）。

• paginate_by (int) – 1ページあたりの行数。

LIMITとOFFSETをより直感的な方法で指定するための便利なメソッド。

この機能はウェブサイトのページネーションを考慮して設計されているため、最初のページはpage=1から始まります。

class SelectQuery

複合クエリを作成するための演算子オーバーロードを実装した、Selectクエリヘルパークラスです。

select_from(*columns)

パラメーター

columns – 内部クエリから選択する1つ以上の列。

戻り値

呼び出し元のクエリをラップする新しいクエリ。

現在の（呼び出し元の）クエリをラップする新しいクエリを作成します。例えば、単純なUNIONクエリがあり、そのUNIONの結果セットに集約を適用する必要があるとします。そのためには、次のような記述が必要になります。

SELECT "u"."owner", COUNT("u"."id") AS "ct"
FROM (
    SELECT "id", "owner", ... FROM "cars"
    UNION
    SELECT "id", "owner", ... FROM "motorcycles"
    UNION
    SELECT "id", "owner", ... FROM "boats") AS "u"
GROUP BY "u"."owner"

select_from()メソッドはこのタイプのクエリの構築を簡素化するために設計されています。

peeweeコードの例

class Car(Model):
    owner = ForeignKeyField(Owner, backref='cars')
    # ... car-specific fields, etc ...

class Motorcycle(Model):
    owner = ForeignKeyField(Owner, backref='motorcycles')
    # ... motorcycle-specific fields, etc ...

class Boat(Model):
    owner = ForeignKeyField(Owner, backref='boats')
    # ... boat-specific fields, etc ...

cars = Car.select(Car.owner)
motorcycles = Motorcycle.select(Motorcycle.owner)
boats = Boat.select(Boat.owner)

union = cars | motorcycles | boats

query = (union
         .select_from(union.c.owner, fn.COUNT(union.c.id))
         .group_by(union.c.owner))

union_all(dest)

destを使用してUNION ALLクエリを作成します。

__add__(dest)

destを使用してUNION ALLクエリを作成します。

union(dest)

destを使用してUNIONクエリを作成します。

__or__(dest)

destを使用してUNIONクエリを作成します。

intersect(dest)

destを使用してINTERSECTクエリを作成します。

__and__(dest)

destを使用してINTERSECTクエリを作成します。

except_(dest)

destを使用してEXCEPTクエリを作成します。「except」はPythonの予約語であるため、メソッド名には末尾に「_」が付いています。

__sub__(dest)

destを使用してEXCEPTクエリを作成します。

class SelectBase

SelectおよびCompoundSelectクエリの基底クラスです。

peek(database[, n=1])

パラメーター

• database (Database) – クエリを実行するデータベース。

• n (int) – 返す行数。

戻り値

n = 1の場合は単一行、それ以外の場合は行のリスト。

クエリを実行し、カーソルの先頭から指定された数の行を返します。この関数は複数回安全に呼び出すことができ、常に最初のN行の結果を返します。

first(database[, n=1])

パラメーター

• database (Database) – クエリを実行するデータベース。

• n (int) – 返す行数。

戻り値

n = 1の場合は単一行、それ以外の場合は行のリスト。

peek()メソッドと同様ですが、n行のみが返されるように、クエリにLIMITが適用されます。同じnの値に対する複数の呼び出しは、複数のクエリ実行にはなりません。

クエリはインプレースで変更されるため、first()を呼び出した後に、同じクエリオブジェクトを使用して完全な結果セットを反復処理することはできません。これも、first()への複数の呼び出しが複数のクエリ実行にならないようにするためです。

scalar(database[, as_tuple=False[, as_dict=False]])

パラメーター

• database (Database) – クエリを実行するデータベース。

• as_tuple (bool) – 結果をタプルとして返しますか？

• as_dict (bool) – 結果を辞書として返しますか？

戻り値

単一のスカラー値。as_tuple = Trueの場合、行タプルが返されます。as_dict = Trueの場合、行辞書が返されます。

結果の最初の行からスカラー値を返します。複数のスカラー値が予想される場合（例：単一クエリ内の複数の集約）、as_tuple=Trueを指定して行タプルを取得できます。

例

query = Note.select(fn.MAX(Note.timestamp))
max_ts = query.scalar(db)

query = Note.select(fn.MAX(Note.timestamp), fn.COUNT(Note.id))
max_ts, n_notes = query.scalar(db, as_tuple=True)

query = Note.select(fn.COUNT(Note.id).alias('count'))
assert query.scalar(db, as_dict=True) == {'count': 123}

count(database[, clear_limit=False])

パラメーター

• database (Database) – クエリを実行するデータベース。

• clear_limit (bool) – カウント時にLIMIT句をクリアします。

戻り値

クエリ結果セット内の行数。

クエリ結果セット内の行数を返します。

SELECT COUNT(1) FROM (<現在のクエリ>)を実行することで実装されています。

exists(database)

パラメーター

database (Database) – クエリを実行するデータベース。

戻り値

現在のクエリに結果が存在するかどうか。

現在のクエリに結果があるかどうかを示すブール値を返します。

get(database)

パラメーター

database (Database) – クエリを実行するデータベース。

戻り値

データベースからの単一行、またはNone。

クエリを実行し、存在する場合は最初の行を返します。複数回呼び出すと、複数のクエリが実行されます。

class CompoundSelectQuery(lhs, op, rhs)

パラメーター

• lhs (SelectBase) – SelectクエリまたはCompoundSelectクエリ。

• op (str) – 演算（例：UNION、INTERSECT、EXCEPT）。

• rhs (SelectBase) – SelectクエリまたはCompoundSelectクエリ。

複合SELECTクエリを表すクラスです。

class Select([from_list=None[, columns=None[, group_by=None[, having=None[, distinct=None[, windows=None[, for_update=None[, for_update_of=None[, for_update_nowait=None[, **kwargs]]]]]]]]]])

パラメーター

• from_list (list) – FROM句のソースのリスト。

• columns (list) – 選択する列または値。

• group_by (list) – グループ化する列または値のリスト。

• having (Expression) – HAVING句の式。

• distinct – ブール値または列のようなオブジェクトのリスト。

• windows (リスト) – Window句のリスト。

• for_update – SELECT…FOR UPDATE を使用するかどうかを示すブール値または文字列。

• for_update_of – FOR UPDATE OF句に使用する1つ以上のテーブル。

• for_update_nowait (bool) – NOWAIT ロックを指定します。

SELECTクエリを表すクラス。

注記

直接インスタンス化することはほとんどなく、通常はTable.select()またはModel.select()のようなファクトリメソッドを使用します。

selectクエリのメソッドはチェーンできます。

データベースからいくつかのユーザーインスタンスを選択する例。idとusernameカラムのみが選択されます。イテレートすると、Userモデルのインスタンスを返します。

query = User.select(User.id, User.username)
for user in query:
    print(user.username)

ユーザーと、ユーザーが作成したツイート数をさらに選択する例。返されるUserインスタンスには、作成されたツイート数に対応する追加属性「count」があります。

query = (User
         .select(User, fn.COUNT(Tweet.id).alias('count'))
         .join(Tweet, JOIN.LEFT_OUTER)
         .group_by(User))
for user in query:
    print(user.username, 'has tweeted', user.count, 'times')

注記

Selectを直接インスタンス化することは可能ですが、通常はメソッドチェーンAPIを使用してクエリを構築します。

columns(*columns)

パラメーター

columns – SELECTする0個以上の列のようなオブジェクト。

SELECTする列または列のような値を指定します。

select(*columns)

パラメーター

columns – SELECTする0個以上の列のようなオブジェクト。

Select.columns()と同じです。後方互換性のために提供されています。

select_extend(*columns)

パラメーター

columns – SELECTする0個以上の列のようなオブジェクト。

現在の選択に指定された列を追加します。

例

def get_users(with_count=False):
    query = User.select()
    if with_count:
        query = (query
                 .select_extend(fn.COUNT(Tweet.id).alias('count'))
                 .join(Tweet, JOIN.LEFT_OUTER)
                 .group_by(User))
    return query

from_(*sources)

パラメーター

sources – FROM句に使用する0個以上のソース。

FROM句で使用するテーブルのようなオブジェクトを指定します。

User = Table('users')
Tweet = Table('tweets')
query = (User
         .select(User.c.username, Tweet.c.content)
         .from_(User, Tweet)
         .where(User.c.id == Tweet.c.user_id))
for row in query.execute(db):
    print(row['username'], '->', row['content'])

join(dest[, join_type='INNER'[, on=None]])

パラメーター

• dest – テーブルまたはテーブルのようなオブジェクト。

• join_type (str) – JOINの種類、デフォルトは「INNER」。

• on (Expression) – 結合述語。

結合の種類は次のいずれかです。

• JOIN.INNER

• JOIN.LEFT_OUTER

• JOIN.RIGHT_OUTER

• JOIN.FULL

• JOIN.FULL_OUTER

• JOIN.CROSS

JOINを表現します。

User = Table('users', ('id', 'username'))
Note = Table('notes', ('id', 'user_id', 'content'))

query = (Note
         .select(Note.content, User.username)
         .join(User, on=(Note.user_id == User.id)))

group_by(*columns)

パラメーター

values – グループ化する0個以上の列のようなオブジェクト。

GROUP BY句を定義します。以前に指定された値は上書きされます。

さらに、特定のテーブルのすべての列を指定するには、個々の列の代わりにテーブル/モデルオブジェクトを渡すことができます。

例

query = (User
         .select(User, fn.Count(Tweet.id).alias('count'))
         .join(Tweet)
         .group_by(User))

group_by_extend(*columns)

パラメーター

values – グループ化する0個以上の列のようなオブジェクト。

GROUP BY句に指定された列を追加します。

having(*expressions)

パラメーター

expressions – HAVING句に含める0個以上の式。

クエリに指定された式をHAVING句に含めます。これらの式は、以前に指定されたHAVING式とANDで結合されます。

distinct(*columns)

パラメーター

columns – 0個以上の列のようなオブジェクト。

このクエリでDISTINCT句を使用するかどうかを示します。Trueの単一値を指定すると、クエリは単純なSELECT DISTINCTを使用します。1つ以上の列を指定すると、SELECT DISTINCT ONになります。

window(*windows)

パラメーター

windows – 0個以上のWindowオブジェクト。

WINDOW句を定義します。以前に指定された値は上書きされます。

例

# Equivalent example Using a Window() instance instead.
window = Window(partition_by=[Sample.counter])
query = (Sample
         .select(
            Sample.counter,
            Sample.value,
            fn.AVG(Sample.value).over(window))
         .window(window)  # Note call to ".window()"
         .order_by(Sample.counter))

for_update([for_update=True[, of=None[, nowait=None]]])

パラメーター

• for_update – ブール値、または目的の式（例：「FOR SHARE」）を示す文字列。

• of – ロックを制限する1つ以上のモデル。

• nowait (bool) – ロック時にNOWAITオプションを指定します。

class _WriteQuery(table[, returning=None[, **kwargs]])

パラメーター

• table (Table) – 書き込み先のテーブル。

• returning (リスト) – RETURNING句の列のリスト。

書き込みクエリの基本クラス。

returning(*returning)

パラメーター

returning – RETURNING句の0個以上の列のようなオブジェクト。

クエリのRETURNING句を指定します（データベースでサポートされている場合）。

query = (User
         .insert_many([{'username': 'foo'},
                       {'username': 'bar'},
                       {'username': 'baz'}])
         .returning(User.id, User.username)
         .namedtuples())
data = query.execute()
for row in data:
    print('added:', row.username, 'with id=', row.id)

class Update(table[, update=None[, **kwargs]])

パラメーター

• table (Table) – 更新するテーブル。

• update (dict) – 更新するデータ。

UPDATEクエリを表すクラス。

例

PageView = Table('page_views')
query = (PageView
         .update({PageView.c.page_views: PageView.c.page_views + 1})
         .where(PageView.c.url == url))
query.execute(database)

from_(*sources)

パラメーター

sources (Source) – 結合する1つ以上のTable、Model、クエリ、またはValuesList。

UPDATE … FROM構文を使用して結合する追加のテーブルを指定します（Postgresでサポートされています）。Postgresのドキュメントには詳細な説明がありますが、要約すると

FROM句が存在する場合、基本的にターゲットテーブルはfrom_listで言及されているテーブルに結合され、結合の各出力行はターゲットテーブルの更新操作を表します。FROMを使用する場合は、結合によって変更する各行に対して最大1つの出力行が生成されるようにする必要があります。

例

# Update multiple users in a single query.
data = [('huey', True),
        ('mickey', False),
        ('zaizee', True)]
vl = ValuesList(data, columns=('username', 'is_admin'), alias='vl')

# Here we'll update the "is_admin" status of the above users,
# "joining" the VALUES() on the "username" column.
query = (User
         .update(is_admin=vl.c.is_admin)
         .from_(vl)
         .where(User.username == vl.c.username))

上記のクエリは、次のSQLを生成します。

UPDATE "users" SET "is_admin" = "vl"."is_admin"
FROM (
    VALUES ('huey', t), ('mickey', f), ('zaizee', t))
    AS "vl"("username", "is_admin")
WHERE ("users"."username" = "vl"."username")

class Insert(table[, insert=None[, columns=None[, on_conflict=None[, **kwargs]]]])

パラメーター

• table (Table) – データを挿入するテーブル。

• insert – 辞書、リスト、またはクエリ。

• columns (list) – insertがリストまたはクエリの時のカラムのリスト。

• on_conflict – 衝突解決戦略。

INSERTクエリを表すクラス。

as_rowcount([as_rowcount=True])

パラメーター

as_rowcount (bool) – (最後に挿入された行IDではなく)変更された行数を返すかどうか。

デフォルトでは、自動的にRETURNINGを使用しないデータベース（現在、SqliteとMySQL）では、Peeweeバージョン3.12から3.14.10までは、バルク挿入を実行するときに変更された行数を返していました。この変更は元に戻され、バルク挿入はデフォルトでcursor.lastrowidの値を返すようになりました。

挿入された行数を受け取る場合は、as_rowcount()を指定してください。

db = MySQLDatabase(...)

query = User.insert_many([...])
# By default, the last rowid is returned:
#last_id = query.execute()

# To get the modified row-count:
rowcount = query.as_rowcount().execute()

on_conflict_ignore([ignore=True])

パラメーター

ignore (bool) – ON CONFLICT IGNORE句を追加するかどうか。

IGNORE衝突解決戦略を指定します。

on_conflict_replace([replace=True])

パラメーター

replace (bool) – ON CONFLICT REPLACE句を追加するかどうか。

REPLACE衝突解決戦略を指定します。

on_conflict([action=None[, update=None[, preserve=None[, where=None[, conflict_target=None[, conflict_where=None[, conflict_constraint=None]]]]]]])

パラメーター

• action (str) – 衝突解決時に実行するアクション。空欄の場合は、アクションは「update」とみなされます。

• update – 列を新しい値にマッピングする辞書。

• preserve – 元のINSERTから値を保持する必要があるカラムのリスト。

• where – 衝突解決を制限する式。

• conflict_target – 制約を構成する列。

• conflict_where – 部分インデックス（WHERE句を持つインデックス）の場合、制約ターゲットと一致させるために必要な式。

• conflict_constraint (str) – 衝突解決に使用する制約の名前。現在、Postgresのみサポート。

衝突解決に使用するOnConflict句のパラメータを指定します。

例

class User(Model):
    username = TextField(unique=True)
    last_login = DateTimeField(null=True)
    login_count = IntegerField()

def log_user_in(username):
    now = datetime.datetime.now()

    # INSERT a new row for the user with the current timestamp and
    # login count set to 1. If the user already exists, then we
    # will preserve the last_login value from the "insert()" clause
    # and atomically increment the login-count.
    userid = (User
              .insert(username=username, last_login=now, login_count=1)
              .on_conflict(
                  conflict_target=[User.username],
                  preserve=[User.last_login],
                  update={User.login_count: User.login_count + 1})
              .execute())
    return userid

特別なEXCLUDED名前空間を使用した例

class KV(Model):
    key = CharField(unique=True)
    value = IntegerField()

# Create one row.
KV.create(key='k1', value=1)

# Demonstrate usage of EXCLUDED.
# Here we will attempt to insert a new value for a given key. If that
# key already exists, then we will update its value with the *sum* of its
# original value and the value we attempted to insert -- provided that
# the new value is larger than the original value.
query = (KV.insert(key='k1', value=10)
         .on_conflict(conflict_target=[KV.key],
                      update={KV.value: KV.value + EXCLUDED.value},
                      where=(EXCLUDED.value > KV.value)))

# Executing the above query will result in the following data being
# present in the "kv" table:
# (key='k1', value=11)
query.execute()

# If we attempted to execute the query *again*, then nothing would be
# updated, as the new value (10) is now less than the value in the
# original row (11).

class Delete

DELETEクエリを表すクラス。

class Index(name, table, expressions[, unique=False[, safe=False[, where=None[, using=None]]]])

パラメーター

• name (str) – インデックス名。

• table (Table) – インデックスを作成するテーブル。

• expressions – インデックスを作成するカラム（または式）のリスト。

• unique (bool) – インデックスがUNIQUEかどうか。

• safe (bool) – IF NOT EXISTS句を追加するかどうか。

• where (Expression) – インデックスのオプションのWHERE句。

• using (str) – インデックスアルゴリズム。

safe([_safe=True])

パラメーター

_safe (bool) – IF NOT EXISTS句を追加するかどうか。

where(*expressions)

パラメーター

expressions – WHERE句に含める式を0個以上。

指定された式をインデックスのWHERE句に含めます。これらの式は、以前に指定されたWHERE式とANDで結合されます。

using([_using=None])

パラメーター

_using (str) – USING句のインデックスアルゴリズムを指定します。

class ModelIndex(model, fields[, unique=False[, safe=True[, where=None[, using=None[, name=None]]]]])

パラメーター

• model (Model) – インデックスを作成するモデルクラス。

• fields (list) – インデックスを作成するフィールド。

• unique (bool) – インデックスがUNIQUEかどうか。

• safe (bool) – IF NOT EXISTS句を追加するかどうか。

• where (Expression) – インデックスのオプションのWHERE句。

• using (str) – インデックスアルゴリズムまたはタイプ、例：「BRIN」、「GiST」、または「GIN」。

• name (str) – オプションのインデックス名。

モデルにインデックスを宣言するための分かりやすい方法。

例

class Article(Model):
    name = TextField()
    timestamp = TimestampField()
    status = IntegerField()
    flags = BitField()

    is_sticky = flags.flag(1)
    is_favorite = flags.flag(2)

# CREATE INDEX ... ON "article" ("name", "timestamp")
idx = ModelIndex(Article, (Article.name, Article.timestamp))

# CREATE INDEX ... ON "article" ("name", "timestamp") WHERE "status" = 1
idx = idx.where(Article.status == 1)

# CREATE UNIQUE INDEX ... ON "article" ("timestamp" DESC, "flags" & 2) WHERE "status" = 1
idx = ModelIndex(
    Article,
    (Article.timestamp.desc(), Article.flags.bin_and(2)),
    unique = True).where(Article.status == 1)

Model.index()も使用できます。

idx = Article.index(Article.name, Article.timestamp).where(Article.status == 1)

モデル定義にインデックスを追加するには、Model.add_index()を使用します。

idx = Article.index(Article.name, Article.timestamp).where(Article.status == 1)

# Add above index definition to the model definition. When you call
# Article.create_table() (or database.create_tables([Article])), the
# index will be created.
Article.add_index(idx)

フィールド

class Field([null=False[, index=False[, unique=False[, column_name=None[, default=None[, primary_key=False[, constraints=None[, sequence=None[, collation=None[, unindexed=False[, choices=None[, help_text=None[, verbose_name=None[, index_type=None]]]]]]]]]]]]])

パラメーター

• null (bool) – フィールドがNULLを許可するかどうか。

• index (bool) – フィールドにインデックスを作成するかどうか。

• unique (bool) – フィールドに一意のインデックスを作成するかどうか。

• column_name (str) – フィールドのカラム名を指定します。

• default – デフォルト値（サーバーではなくPythonで強制されます）。

• primary_key (bool) – フィールドが主キーかどうか。

• constraints (list) – カラムに適用する制約のリスト。例：[Check('price > 0')]。

• sequence (str) – フィールドのシーケンス名。

• collation (str) – フィールドの照合順序名。

• unindexed (bool) – フィールドをUNINDEXEDと宣言します（sqliteのみ）。

• choices (list) – 列値と表示ラベルをマッピングした2要素タプルのイテラブル。メタデータ目的でのみ使用され、例えばフィールド値のドロップダウンを表示する際に役立ちます。

• help_text (str) – フィールドのヘルプテキスト。メタデータ目的でのみ使用されます。

• verbose_name (str) – フィールドの分かりやすい名前。メタデータ目的でのみ使用されます。

• index_type (str) – インデックスの種類を指定します (PostgreSQLのみ)。例: ‘BRIN’。

Model のフィールドは、テーブルの列に相当します。

field_type = '<some field type>'

このフィールドをカラムタイプにマッピングするために使用される属性 (例: “INT”)。詳細については、ソースコードのFIELDオブジェクトを参照してください。

column

基底となるColumnオブジェクトへの参照を取得します。

model

フィールドがバインドされているモデル。

name

フィールドの名前。

db_value(value)

Pythonの値を、データベースに格納するのに適した値に変換します。特殊なデータ型を扱うサブクラスでは、このメソッドをオーバーライドする必要があるでしょう。

python_value(value)

データベースからの値をPythonオブジェクトに変換します。特殊なデータ型を扱うサブクラスでは、このメソッドをオーバーライドする必要があるでしょう。

coerce(value)

このメソッドは、デフォルトではdb_value()とpython_value()の両方で使用されるショートハンドです。

パラメーター

value – アプリまたはバックエンドからの任意のデータ

戻り値の型

Pythonのデータ型

class IntegerField

整数を格納するためのフィールドクラス。

class BigIntegerField

大きな整数を格納するためのフィールドクラス (データベースでサポートされている場合)。

class SmallIntegerField

小さな整数を格納するためのフィールドクラス (データベースでサポートされている場合)。

class AutoField

自動インクリメントする主キーを格納するためのフィールドクラス。

注記

SQLiteでは、パフォーマンス上の理由から、デフォルトの主キータイプは、新しい値に対して最大既存値 + 1 を使用し、最大値 + 1 ではありません。これは、削除されたレコードの主キーが再利用される可能性があることを意味します。SQLiteではデフォルトで外部キーが無効になっている (ON DELETE は明示的に指定しても無視される) ことと合わせて、予期せぬ危険な動作につながる可能性があります。これを回避するには、AutoIncrementFieldとpragmas=[('foreign_keys', 'on')]の両方、または一方をSqliteDatabaseのインスタンス化時に使用することをお勧めします。

class BigAutoField

64ビットを使用して自動インクリメントする主キーを格納するためのフィールドクラス。

class IdentityField([generate_always=False])

パラメーター

generate_always (bool) – 指定されている場合、IDは常に生成されます (INSERT時に値を明示的に指定すると、プログラミングエラーが発生します)。それ以外の場合は、必要に応じてのみID値が生成されます。

新しいPostgreSQL 10の *IDENTITY* 列タイプを使用して、自動インクリメントする主キーを格納するためのフィールドクラス。列定義は次のようになります。

id = IdentityField()
# "id" INT GENERATED BY DEFAULT AS IDENTITY NOT NULL PRIMARY KEY

注意

PostgreSQL 10.0以降でのみサポートされています。

class FloatField

浮動小数点数を格納するためのフィールドクラス。

class DoubleField

倍精度浮動小数点数を格納するためのフィールドクラス。

class DecimalField([max_digits=10[, decimal_places=5[, auto_round=False[, rounding=None[, **kwargs]]]]])

パラメーター

• max_digits (int) – 格納する最大桁数。

• decimal_places (int) – 最大精度。

• auto_round (bool) – 値を自動的に丸めます。

• rounding –

  decimal.DefaultContext.roundingがデフォルトです。

  10進数を格納するためのフィールドクラス。値はdecimal.Decimalオブジェクトとして表されます。

class CharField([max_length=255])

文字列を格納するためのフィールドクラス。

注記

長さを超える値は、自動的に切り捨てられません。

class FixedCharField

固定長の文字列を格納するためのフィールドクラス。

注記

長さを超える値は、自動的に切り捨てられません。

class TextField

テキストを格納するためのフィールドクラス。

class BlobField

バイナリデータを格納するためのフィールドクラス。

class BitField

64ビット整数列にオプションを格納するためのフィールドクラス。

使用方法

class Post(Model):
    content = TextField()
    flags = BitField()

    is_favorite = flags.flag(1)
    is_sticky = flags.flag(2)
    is_minimized = flags.flag(4)
    is_deleted = flags.flag(8)

>>> p = Post()
>>> p.is_sticky = True
>>> p.is_minimized = True
>>> print(p.flags)  # Prints 4 | 2 --> "6"
6
>>> p.is_favorite
False
>>> p.is_sticky
True

Postクラスのフラグを使用して、クエリで式を構築することもできます。

# Generates a WHERE clause that looks like:
# WHERE (post.flags & 1 != 0)
query = Post.select().where(Post.is_favorite)

# Query for sticky + favorite posts:
query = Post.select().where(Post.is_sticky & Post.is_favorite)

BitFieldで1つ以上のビットを一括更新する場合は、ビット演算子を使用して1つ以上のビットを設定またはクリアできます。

# Set the 4th bit on all Post objects.
Post.update(flags=Post.flags | 8).execute()

# Clear the 1st and 3rd bits on all Post objects.
Post.update(flags=Post.flags & ~(1 | 4)).execute()

単純な操作の場合、フラグは個々のビットを設定またはクリアするための便利なset()とclear()メソッドを提供します。

# Set the "is_deleted" bit on all posts.
Post.update(flags=Post.is_deleted.set()).execute()

# Clear the "is_deleted" bit on all posts.
Post.update(flags=Post.is_deleted.clear()).execute()

flag([value=None])

パラメーター

value (int) – フラグに関連付けられた値。通常は2の累乗です。

全体的な値の特定のビットを取得または設定できるディスクリプタを返します。クラス自体でアクセスされた場合、クエリで使用できるExpressionオブジェクトを返します。

値が提供されない場合、各フラグは2の累乗であると仮定されます。そのため、4つのフラグがある場合、値は1、2、4、8になります。

class BigBitField

BLOBに任意の大きさのビットマップを格納するためのフィールドクラス。このフィールドは必要に応じて基底となるバッファを拡張し、格納されているビットデータの数に対応する十分なバイト数のデータが確保されます。

使用例

class Bitmap(Model):
    data = BigBitField()

bitmap = Bitmap()

# Sets the ith bit, e.g. the 1st bit, the 11th bit, the 63rd, etc.
bits_to_set = (1, 11, 63, 31, 55, 48, 100, 99)
for bit_idx in bits_to_set:
    bitmap.data.set_bit(bit_idx)

# We can test whether a bit is set using "is_set":
assert bitmap.data.is_set(11)
assert not bitmap.data.is_set(12)

# We can clear a bit:
bitmap.data.clear_bit(11)
assert not bitmap.data.is_set(11)

# We can also "toggle" a bit. Recall that the 63rd bit was set earlier.
assert bitmap.data.toggle_bit(63) is False
assert bitmap.data.toggle_bit(63) is True
assert bitmap.data.is_set(63)

# BigBitField supports item accessor by bit-number, e.g.:
assert bitmap.data[63]
bitmap.data[0] = 1
del bitmap.data[0]

# We can also combine bitmaps using bitwise operators, e.g.
b = Bitmap(data=b'\x01')
b.data |= b'\x02'
assert list(b.data) == [1, 1, 0, 0, 0, 0, 0, 0]
assert len(b.data) == 1

clear()

ビットマップをクリアし、長さを0に設定します。

set_bit(idx)

パラメーター

idx (int) – 設定するビット。0から始まるインデックス。

ビットマップの *idx* 番目のビットを設定します。

clear_bit(idx)

パラメーター

idx (int) – 0から始まるインデックスで指定された、クリアするビット。

ビットマップのidx番目のビットをクリアします。

toggle_bit(idx)

パラメーター

idx (int) – 0から始まるインデックスで指定された、トグルするビット。

戻り値

ビットが設定されているかどうか。

ビットマップのidx番目のビットをトグルし、ビットが設定されているかどうかを返します。

例

>>> bitmap = Bitmap()
>>> bitmap.data.toggle_bit(10)  # Toggle the 10th bit.
True
>>> bitmap.data.toggle_bit(10)  # This will clear the 10th bit.
False

is_set(idx)

パラメーター

idx (int) – 0から始まるインデックスで指定されたビットインデックス。

戻り値

ビットが設定されているかどうか。

idx番目のビットが設定されているかどうかを示すブール値を返します。

__getitem__(idx)

is_set()と同じです。

__setitem__(idx, value)

idxで指定されたビットをvalue（TrueまたはFalse）に設定します。

__delitem__(idx)

clear_bit()と同じです。

__len__()

ビットマップの長さをバイト単位で返します。

__iter__()

ビットマップ内の各ビットに対して1または0を返すイテレータを返します。

__and__(other)

パラメーター

other – BigBitField、bytes、bytearray、またはmemoryviewオブジェクト。

戻り値

2つのビットマップのビット単位のand演算。

__or__(other)

パラメーター

other – BigBitField、bytes、bytearray、またはmemoryviewオブジェクト。

戻り値

2つのビットマップのビット単位のor演算。

__xor__(other)

パラメーター

other – BigBitField、bytes、bytearray、またはmemoryviewオブジェクト。

戻り値

2つのビットマップのビット単位のxor演算。

class UUIDField

uuid.UUIDオブジェクトを保存するためのフィールドクラス。PostgreSQLの場合、基となるカラムのデータ型はUUIDになります。SQLiteとMySQLにはネイティブのUUID型がないため、UUIDは代わりにVARCHARとして保存されます。

class BinaryUUIDField

uuid.UUIDオブジェクトを16バイトで効率的に保存するためのフィールドクラス。データベースのBLOBデータ型（またはMySQLのVARBINARY、PostgreSQLのBYTEA）を使用します。

class DateTimeField([formats=None[, **kwargs]])

パラメーター

formats (list) – 文字列を日付時刻に変換する際に使用するフォーマット文字列のリスト。

datetime.datetimeオブジェクトを保存するためのフィールドクラス。

日付時刻をエンコードできるフォーマットのリストを含む特別なパラメータformatsを受け入れます（ネイティブの日付時刻データ型をサポートしていないデータベースの場合）。デフォルトでサポートされるフォーマットは、

'%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond
'%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second
'%Y-%m-%d' # year-month-day

注記

SQLiteにはネイティブの日付時刻データ型がないため、日付時刻は文字列として保存されます。これはPeeweeによって透過的に処理されますが、既存のデータがある場合は、YYYY-mm-dd HH:MM:SSまたはその他のサポートされているフォーマットで保存されていることを確認する必要があります。

year

クエリでカラムに保存されている値の年を参照します。

Blog.select().where(Blog.pub_date.year == 2018)

month

クエリでカラムに保存されている値の月を参照します。

day

クエリでカラムに保存されている値の日を参照します。

hour

クエリでカラムに保存されている値の時を参照します。

minute

クエリでカラムに保存されている値の分を参照します。

second

クエリでカラムに保存されている値の秒を参照します。

to_timestamp()

指定された日付時刻値を数値タイムスタンプとして扱うことができる、データベース固有の関数呼び出しを返すメソッド。これは、互換性のある方法で日付の計算などのタスクを簡素化する場合があります。

例

# Find all events that are exactly 1 hour long.
query = (Event
         .select()
         .where((Event.start.to_timestamp() + 3600) ==
                Event.stop.to_timestamp())
         .order_by(Event.start))

truncate(date_part)

パラメーター

date_part (str) – year、month、day、hour、minute、またはsecond。

戻り値

日付時刻を指定された解像度に切り捨てる式ノード。

カラムの値を指定された部分に切り捨てます。このメソッドは、たとえば、特定の月内のすべての行を見つけるのに役立ちます。

class DateField([formats=None[, **kwargs]])

パラメーター

formats (list) – 文字列を日付に変換する際に使用するフォーマット文字列のリスト。

datetime.dateオブジェクトを保存するためのフィールドクラス。

日付時刻をエンコードできるフォーマットのリストを含む特別なパラメータformatsを受け入れます（ネイティブの日付データ型をサポートしていないデータベースの場合）。デフォルトでサポートされるフォーマットは、

'%Y-%m-%d' # year-month-day
'%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second
'%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond

注記

入力値がフォーマットに一致しない場合は、そのまま返されます。

year

クエリでカラムに保存されている値の年を参照します。

Person.select().where(Person.dob.year == 1983)

month

クエリでカラムに保存されている値の月を参照します。

day

クエリでカラムに保存されている値の日を参照します。

to_timestamp()

DateTimeField.to_timestamp()を参照してください。

truncate(date_part)

DateTimeField.truncate()を参照してください。ただし、DateFieldでは、year、month、およびdayのみが意味を持ちます。

class TimeField([formats=None[, **kwargs]])

パラメーター

formats (list) – 文字列を時刻オブジェクトに変換する際に使用するフォーマット文字列のリスト。

datetime.timeオブジェクト（timedeltaではない）を格納するためのフィールドクラス。

（ネイティブな時刻データ型をサポートしていないデータベース向けに）datetimeをエンコードできるフォーマットのリストを含む特別なパラメータformatsを受け入れます。デフォルトでサポートされるフォーマットは次のとおりです。

'%H:%M:%S.%f' # hour:minute:second.microsecond
'%H:%M:%S' # hour:minute:second
'%H:%M' # hour:minute
'%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond
'%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second

注記

入力値がフォーマットに一致しない場合は、そのまま返されます。

hour

クエリでカラムに保存されている値の時を参照します。

evening_events = Event.select().where(Event.time.hour > 17)

minute

クエリでカラムに保存されている値の分を参照します。

second

クエリでカラムに保存されている値の秒を参照します。

class TimestampField([resolution=1[, utc=False[, **kwargs]]])

パラメーター

• resolution – 10の累乗、または格納する小数点以下の桁数を示す指数として指定できます。

• utc (bool) – タイムスタンプをUTCとして扱うかどうか。

日付時刻を整数型のタイムスタンプとして格納するためのフィールドクラス。10の累乗をかけることで、秒未満の精度もサポートします。

resolutionパラメータが0または1の場合、タイムスタンプは秒単位で格納されます。2から6の間の解像度は、小数点以下の桁数として扱われます。たとえば、resolution=3はミリ秒に対応します。あるいは、10の倍数として小数点を指定することもでき、resolution=10は1/10秒の解像度で格納されます。

resolutionパラメータは、0～6または10、100など1000000（マイクロ秒の解像度）まで指定できます。これにより、秒未満の精度を維持しながら、IntegerFieldを使用して格納できます。デフォルトは秒単位の解像度です。

また、タイムスタンプをUTCにするかどうかを示すブール値のパラメータutcも受け入れます。デフォルトはFalseです。

最後に、フィールドdefaultは現在のタイムスタンプです。この動作を望まない場合は、明示的にdefault=Noneを渡してください。

class IPField

IPv4アドレスを効率的に（整数として）格納するためのフィールドクラス。

class BooleanField

ブール値を格納するためのフィールドクラス。

class BareField([coerce=None[, **kwargs]])

パラメーター

coerce – 生の値を特定の形式に変換するために使用するオプションの関数。

データ型を指定しないフィールドクラス（**SQLite専用**）。

データ型が強制されないため、データ型をまったく指定せずにフィールドを宣言できます。SQLite仮想テーブルがメタカラムまたは型なしカラムを使用することも一般的であるため、そのような場合にも型なしフィールドを使用することをお勧めします。

データベースから取得した値を受け取り、適切なPython型に変換する関数である特別なcoerceパラメータを受け入れます。

class ForeignKeyField(model[, field=None[, backref=None[, on_delete=None[, on_update=None[, deferrable=None[, object_id_name=None[, lazy_load=True[, constraint_name=None[, **kwargs]]]]]]]]])

パラメーター

• model (Model) – 参照するモデル、または自己参照外部キーを宣言する場合は文字列'self'。

• field (Field) – modelで参照するフィールド（デフォルトは主キー）。

• backref (str) – 逆参照のアクセッサ名、または逆参照アクセッサを無効にする場合は「+」。

• on_delete (str) – ON DELETEアクション（例：'CASCADE'）。

• on_update (str) – ON UPDATEアクション。

• deferrable (str) – 制約がいつ適用されるかを制御します（例：'INITIALLY DEFERRED'）。

• object_id_name (str) – オブジェクトIDアクセッサの名前。

• lazy_load (bool) – 外部キーフィールド属性にアクセスしたときに関連オブジェクトを取得します（まだロードされていない場合）。これが無効になっている場合、外部キーフィールドにアクセスすると、外部キー列に格納されている値が返されます。

• constraint_name (str) – 外部キー制約に使用する（オプションの）名前。

外部キーを格納するためのフィールドクラス。

class User(Model):
    name = TextField()

class Tweet(Model):
    user = ForeignKeyField(User, backref='tweets')
    content = TextField()

# "user" attribute
>>> some_tweet.user
<User: charlie>

# "tweets" backref attribute
>>> for tweet in charlie.tweets:
...     print(tweet.content)
Some tweet
Another tweet
Yet another tweet

外部キー、結合、モデル間の関係の詳細については、Relationships and Joinsを参照してください。

注記

外部キーには特定のfield_typeがありません。関連付けられているモデルの主キーの型に応じてフィールド型が決定されます。

注記

fieldを手動で指定する場合は、そのフィールドは主キーであるか、一意制約を持っている必要があります。

注記

SQLiteでの外部キーには注意が必要です。デフォルトでは、ON DELETEは効果がなく、データベースの整合性に予期しない（そして通常は望ましくない）影響を与える可能性があります。on_deleteを指定しなくても、デフォルトのON DELETE動作（データを変更せずに失敗する）は発生せず、データがサイレントに再リンクされるため、影響を受ける可能性があります。最も安全な方法は、SqliteDatabaseをインスタンス化するときにpragmas={'foreign_keys': 1}を指定することです。

class DeferredForeignKey(rel_model_name[, **kwargs])

パラメーター

rel_model_name (str) – 参照するモデル名。

遅延外部キーを表すフィールドクラス。たとえば、循環外部キー参照などに役立ちます。

class Husband(Model):
    name = TextField()
    wife = DeferredForeignKey('Wife', deferrable='INITIALLY DEFERRED')

class Wife(Model):
    name = TextField()
    husband = ForeignKeyField(Husband, deferrable='INITIALLY DEFERRED')

上記の例では、Wifeモデルが宣言されると、外部キーHusband.wifeが自動的に解決され、通常のForeignKeyFieldに変換されます。

警告

DeferredForeignKey参照は、モデルクラスが宣言および作成されたときに解決されます。つまり、既にインポートおよび作成されているモデルクラスにDeferredForeignKeyを宣言した場合、遅延外部キーインスタンスは解決されません。たとえば

class User(Model):
    username = TextField()

class Tweet(Model):
    # This will never actually be resolved, because the User
    # model has already been declared.
    user = DeferredForeignKey('user', backref='tweets')
    content = TextField()

このような場合は、通常のForeignKeyFieldを使用するか、次のように遅延外部キーを手動で解決できます。

# Tweet.user will be resolved into a ForeignKeyField:
DeferredForeignKey.resolve(User)

class ManyToManyField(model[, backref=None[, through_model=None[, on_delete=None[, on_update=None]]]])

パラメーター

• model (Model) – 関連付けるモデル。

• backref (str) – 逆参照のためのアクセサ名。

• through_model (Model) – 中間テーブルとして使用するModel。指定しない場合、シンプルな中間テーブルが自動的に作成されます。

• on_delete (str) – ON DELETE アクション（例: 'CASCADE'）。中間モデルの外部キーに使用されます。

• on_update (str) – ON UPDATE アクション。中間モデルの外部キーに使用されます。

Djangoにインスパイアされた、多対多の関係を扱うためのシンプルなインターフェースを提供します。多対多の関係は、通常、2つの関連するモデルへの外部キーを持つ結合テーブルを作成することで実装されます。例えば、大学生のシラバス管理システムを構築する場合、学生とコースの関係は多対多になります。標準APIを使用したスキーマは以下のようになります。

注意

これは、関連付けられた列がないという意味で、フィールドではありません。むしろ、中間モデルを介して関連付けられたデータの行にアクセスするための便利なインターフェースを提供します。

ManyToManyFieldを使用しない（標準の）多対多の関係の宣言方法

class Student(Model):
    name = CharField()

class Course(Model):
    name = CharField()

class StudentCourse(Model):
    student = ForeignKeyField(Student)
    course = ForeignKeyField(Course)

特定の生徒のコースをクエリするには、結合テーブルを介して結合します。

# List the courses that "Huey" is enrolled in:
courses = (Course
           .select()
           .join(StudentCourse)
           .join(Student)
           .where(Student.name == 'Huey'))
for course in courses:
    print(course.name)

ManyToManyFieldは、結合テーブル内のデータのクエリと変更のためのフィールドのようなAPIを提供することにより、このユースケースを簡素化するために設計されています。ManyToManyFieldを使用したコードは以下のようになります。

class Student(Model):
    name = CharField()

class Course(Model):
    name = CharField()
    students = ManyToManyField(Student, backref='courses')

注記

Peeweeの観点からは、ManyToManyFieldがどのモデルにあるかは問題ではありません。逆参照は単なる鏡像だからです。ただし、有効なPythonを書くためには、最初のモデルの名前がスコープ内にあるように、2番目のモデルにManyToManyFieldを追加する必要があります。

学生とコースの関係を保存するための結合テーブルはまだ必要です。このモデルは、get_through_model()メソッドを呼び出すことでアクセスできます。これはテーブル作成時に役立ちます。

# Create tables for the students, courses, and relationships between
# the two.
db.create_tables([
    Student,
    Course,
    Course.students.get_through_model()])

モデルインスタンスからアクセスされた場合、ManyToManyFieldは、関連オブジェクトのセットを表すModelSelectを公開します。インタラクティブシェルを使用して、これがどのように機能するかを見てみましょう。

>>> huey = Student.get(Student.name == 'huey')
>>> [course.name for course in huey.courses]
['English 101', 'CS 101']

>>> engl_101 = Course.get(Course.name == 'English 101')
>>> [student.name for student in engl_101.students]
['Huey', 'Mickey', 'Zaizee']

オブジェクト間に新しい関係を追加するには、ManyToManyField属性にオブジェクトを直接割り当てるか、add()メソッドを呼び出すことができます。2つの違いは、単純に割り当てることで既存の関係がクリアされるのに対し、add()は既存の関係を維持できることです。

>>> huey.courses = Course.select().where(Course.name.contains('english'))
>>> for course in huey.courses.order_by(Course.name):
...     print(course.name)
English 101
English 151
English 201
English 221

>>> cs_101 = Course.get(Course.name == 'CS 101')
>>> cs_151 = Course.get(Course.name == 'CS 151')
>>> huey.courses.add([cs_101, cs_151])
>>> [course.name for course in huey.courses.order_by(Course.name)]
['CS 101', 'CS151', 'English 101', 'English 151', 'English 201',
 'English 221']

これはかなりの数のコースなので、200レベルの英語コースを削除しましょう。オブジェクトを削除するには、remove()メソッドを使用します。

>>> huey.courses.remove(Course.select().where(Course.name.contains('2'))
2
>>> [course.name for course in huey.courses.order_by(Course.name)]
['CS 101', 'CS151', 'English 101', 'English 151']

コレクションからすべての関係を削除するには、clear()メソッドを使用できます。英語101がキャンセルされたので、すべての学生を削除する必要があります。

>>> engl_101 = Course.get(Course.name == 'English 101')
>>> engl_101.students.clear()

注記

標準のPeewee APIを使用した多対多の関係の実装の概要については、Implementing Many to Manyセクションを参照してください。最も単純なケースを除いて、標準APIを使用して多対多を実装する方が良いでしょう。

through_model

多対多結合テーブルを表すModel。明示的に宣言されない場合は自動生成されます。

add(value[, clear_existing=True])

パラメーター

• value – Modelインスタンス、モデルインスタンスのリスト、またはSelectQuery。

• clear_existing (bool) – 既存の関係を削除するかどうか。

valueを現在のインスタンスに関連付けます。単一のモデルインスタンス、モデルインスタンスのリスト、またはModelSelectを渡すことができます。

コード例

# Huey needs to enroll in a bunch of courses, including all
# the English classes, and a couple Comp-Sci classes.
huey = Student.get(Student.name == 'Huey')

# We can add all the objects represented by a query.
english_courses = Course.select().where(
    Course.name.contains('english'))
huey.courses.add(english_courses)

# We can also add lists of individual objects.
cs101 = Course.get(Course.name == 'CS 101')
cs151 = Course.get(Course.name == 'CS 151')
huey.courses.add([cs101, cs151])

remove(value)

パラメーター

value – Modelインスタンス、モデルインスタンスのリスト、またはModelSelect。

valueを現在のインスタンスから関連付け解除します。add()と同様に、モデルインスタンス、モデルインスタンスのリスト、またはModelSelectを渡すことができます。

コード例

# Huey is currently enrolled in a lot of english classes
# as well as some Comp-Sci. He is changing majors, so we
# will remove all his courses.
english_courses = Course.select().where(
    Course.name.contains('english'))
huey.courses.remove(english_courses)

# Remove the two Comp-Sci classes Huey is enrolled in.
cs101 = Course.get(Course.name == 'CS 101')
cs151 = Course.get(Course.name == 'CS 151')
huey.courses.remove([cs101, cs151])

clear()

関連付けられたすべてのオブジェクトを削除します。

コード例

# English 101 is canceled this semester, so remove all
# the enrollments.
english_101 = Course.get(Course.name == 'English 101')
english_101.students.clear()

get_through_model()

多対多結合テーブルを表すModelを返します。これは、through_modelパラメータを使用してフィールドをインスタンス化するときに、手動で指定できます。through_modelが指定されていない場合、自動的に作成されます。

ManyToManyFieldを使用するアプリケーションのテーブルを作成する際には、**中間テーブルを明示的に作成する必要があります**。

# Get a reference to the automatically-created through table.
StudentCourseThrough = Course.students.get_through_model()

# Create tables for our two models as well as the through model.
db.create_tables([
    Student,
    Course,
    StudentCourseThrough])

class DeferredThroughModel

依存関係のために、NameErrorを発生させることなくモデルまたは多対多フィールドを宣言できない場合の中間モデルのプレースホルダー。

例

class Note(BaseModel):
    content = TextField()

NoteThroughDeferred = DeferredThroughModel()

class User(BaseModel):
    username = TextField()
    notes = ManyToManyField(Note, through_model=NoteThroughDeferred)

# Cannot declare this before "User" since it has a foreign-key to
# the User model.
class NoteThrough(BaseModel):
    note = ForeignKeyField(Note)
    user = ForeignKeyField(User)

# Resolve dependencies.
NoteThroughDeferred.set_model(NoteThrough)

class CompositeKey(*field_names)

パラメーター

field_names – プライマリキーを構成するフィールドの名前。

複数の列で構成されるプライマリキー。他のフィールドとは異なり、複合キーはフィールドが定義された後にモデルのMetaクラスで定義されます。プライマリキーとして使用するフィールドの文字列名をパラメータとして受け取ります。

class BlogTagThrough(Model):
    blog = ForeignKeyField(Blog, backref='tags')
    tag = ForeignKeyField(Tag, backref='blogs')

    class Meta:
        primary_key = CompositeKey('blog', 'tag')

スキーママネージャー

class SchemaManager(model[, database=None[, **context_options]])

パラメーター

• model (Model) – モデルクラス。

• データベース (データベース) – 指定がない場合は、model._meta.database がデフォルトになります。

指定されたモデルのテーブルとインデックスの作成と削除を管理するためのメソッドを提供します。

create_table([safe=True[, **options]])

パラメーター

• safe (bool) – IF NOT EXISTS句を指定します。

• options – 任意のオプション。

指定されたモデルに対してCREATE TABLEクエリを実行します。

drop_table([safe=True[, drop_sequences=True[, **options]]])

パラメーター

• safe (bool) – IF EXISTS句を指定します。

• drop_sequences (bool) – テーブルの列に関連付けられたシーケンスを削除します（PostgreSQLのみ）。

• options – 任意のオプション。

指定されたモデルに対してDROP TABLEクエリを実行します。

truncate_table([restart_identity=False[, cascade=False]])

パラメーター

• restart_identity (bool) – IDシーケンスを再開します（PostgreSQLのみ）。

• cascade (bool) – 関連テーブルも切り詰めます（PostgreSQLのみ）。

指定されたモデルに対してTRUNCATE TABLEを実行します。データベースがSQLiteの場合（TRUNCATEをサポートしていない）、同等のDELETEクエリが実行されます。

create_indexes([safe=True])

パラメーター

safe (bool) – IF NOT EXISTS句を指定します。

モデルに対して定義されているインデックスについて、CREATE INDEXクエリを実行します。

drop_indexes([safe=True])

パラメーター

safe (bool) – IF EXISTS句を指定します。

モデルに対して定義されているインデックスについて、DROP INDEXクエリを実行します。

create_sequence(field)

パラメーター

field (Field) – シーケンスを指定するFieldインスタンス。

指定されたFieldに対してシーケンスを作成します。

drop_sequence(field)

パラメーター

field (Field) – シーケンスを指定するFieldインスタンス。

指定されたFieldに対してシーケンスを削除します。

create_foreign_key(field)

パラメーター

field (ForeignKeyField) – 追加する外部キー制約フィールド。

指定されたフィールドに対して外部キー制約を追加します。テーブル作成の一部として外部キー制約が作成されるため、ほとんどの場合、このメソッドは必要ありません。DeferredForeignKeyを使用して循環的な外部キー関係を作成する場合を除きます。そのような場合は、最初にテーブルを作成してから、遅延外部キーの制約を追加する必要があります。

class Language(Model):
    name = TextField()
    selected_snippet = DeferredForeignKey('Snippet')

class Snippet(Model):
    code = TextField()
    language = ForeignKeyField(Language, backref='snippets')

# Creates both tables but does not create the constraint for the
# Language.selected_snippet foreign key (because of the circular
# dependency).
db.create_tables([Language, Snippet])

# Explicitly create the constraint:
Language._schema.create_foreign_key(Language.selected_snippet)

詳細については、「循環外部キー依存関係」のドキュメントを参照してください。

警告

SQLiteは既存のテーブルの変更に対するサポートが限られているため、既存のSQLiteテーブルに外部キー制約を追加することはできません。

create_all([safe=True[, **table_options]])

パラメーター

safe (bool) – IF NOT EXISTSを指定するかどうか。

モデルのシーケンス、インデックス、およびテーブルを作成します。

drop_all([safe=True[, drop_sequences=True[, **options]]])

パラメーター

• safe (bool) – IF EXISTSを指定するかどうか。

• drop_sequences (bool) – テーブルの列に関連付けられたシーケンスを削除します（PostgreSQLのみ）。

• options – 任意のオプション。

モデルのテーブルと関連するインデックスを削除します。

モデル

class Metadata(model[, database=None[, table_name=None[, indexes=None[, primary_key=None[, constraints=None[, schema=None[, only_save_dirty=False[, depends_on=None[, options=None[, without_rowid=False[, strict_tables=False[, **kwargs]]]]]]]]]]]]])

パラメーター

• model (Model) – モデルクラス。

• database (データベース) – モデルがバインドされているデータベース。

• table_name (str) – モデルのテーブル名を指定します。

• indexes (list) – ModelIndexオブジェクトのリスト。

• primary_key – モデルの主キー（CompositeKeyである場合、または主キーがない場合はFalseのみ指定）。

• constraints (list) – テーブル制約のリスト。

• schema (str) – テーブルが存在するスキーマ。

• only_save_dirty (bool) – save()が呼び出された場合、変更されたフィールドのみ保存します。

• options (dict) – モデルの任意のオプション。

• without_rowid (bool) – WITHOUT ROWIDを指定します（SQLiteのみ）。

• strict_tables (bool) – STRICTを指定します（SQLiteのみ、3.37以降が必要です）。

• kwargs – 任意の設定属性と値。

Modelのメタデータを保存します。

このクラスは直接インスタンス化しないでください。 Modelクラスの内側のMetaクラスの属性を使用してインスタンス化されます。メタデータ属性はその後Model._metaで使用できます。

table

基となるTableオブジェクトへの参照を返します。

model_graph([refs=True[, backrefs=True[, depth_first=True]]])

パラメーター

• refs (bool) – 外部キー参照に従います。

• backrefs (bool) – 外部キー逆参照に従います。

• depth_first (bool) – 深さ優先探索を行います（幅優先の場合はFalse）。

モデルグラフをトラバースし、(外部キーフィールド、モデルクラス、is_backref)からなる3要素のタプルのリストを返します。

set_database(database)

パラメーター

database (データベース) – モデルをバインドするデータベースオブジェクト。

モデルクラスを指定されたDatabaseインスタンスにバインドします。

警告

このAPIは使用必要ありません。代わりに、実行時にModelデータベースを変更するには、次のいずれかを使用します。

• Model.bind()

• Model.bind_ctx()（コンテキストマネージャのスコープに対してバインドします）。

• Database.bind()

• Database.bind_ctx()

set_table_name(table_name)

パラメーター

table_name (str) – モデルをバインドするテーブル名。

実行時にモデルクラスを指定されたテーブル名にバインドします。

class SubclassAwareMetadata

Modelサブクラスを追跡するMetadataサブクラス。プロジェクト内のすべてのモデルを追跡する必要がある場合に役立ちます。

例

from peewee import SubclassAwareMetadata

class Base(Model):
    class Meta:
        database = db
        model_metadata_class = SubclassAwareMetadata

# Create 3 model classes that inherit from Base.
class A(Base): pass
class B(Base): pass
class C(Base): pass

# Now let's make a helper for changing the `schema` for each Model.
def change_schema(schema):
    def _update(model):
        model._meta.schema = schema
    return _update

# Set all models to use "schema1", e.g. "schema1.a", "schema1.b", etc.
# Will apply the function to every subclass of Base.
Base._meta.map_models(change_schema('schema1'))

# Set all models to use "schema2", e.g. "schema2.a", "schema2.b", etc.
Base._meta.map_models(change_schema('schema2'))

map_models(fn)

すべてのサブクラスに関数を適用します。

class Model(**kwargs)

パラメーター

kwargs – モデルを初期化するフィールド名と値のマッピング。

Model クラスは、データベーステーブルを操作するための高レベルな抽象化を提供します。モデルは、データベーステーブル（またはビューなどのテーブルのようなオブジェクト）と1対1のマッピングです。Model のサブクラスは、任意の数の Field インスタンスをクラス属性として宣言します。これらのフィールドは、テーブルのカラムに対応します。

select()、update()、insert()、delete() などのテーブルレベルの操作は、クラスメソッドとして実装されています。 save() や delete_instance() などの行レベルの操作は、インスタンスメソッドとして実装されています。

例

db = SqliteDatabase(':memory:')

class User(Model):
    username = TextField()
    join_date = DateTimeField(default=datetime.datetime.now)
    is_admin = BooleanField(default=False)

admin = User(username='admin', is_admin=True)
admin.save()

classmethod alias([alias=None])

パラメーター

alias (str) – 別名（オプション）。

戻り値

ModelAlias インスタンス。

モデルクラスへの別名を作成します。モデルの別名を使用すると、自己結合やサブクエリなど、クエリ内で同じ Model を複数回参照できます。

例

Parent = Category.alias()
sq = (Category
      .select(Category, Parent)
      .join(Parent, on=(Category.parent == Parent.id))
      .where(Parent.name == 'parent category'))

classmethod select(*fields)

パラメーター

fields – モデルクラス、フィールドインスタンス、関数、または式のリスト。引数を指定しないと、デフォルトで指定されたモデルのすべてのカラムが選択されます。

戻り値

ModelSelect クエリ。

SELECT クエリを作成します。明示的にフィールドを指定しない場合、クエリはデフォルトでモデルで定義されているすべてのフィールドを選択します。ただし、サブクエリとしてクエリを使用している場合は、デフォルトで主キーのみが選択されます。

すべてのカラムを選択する例

query = User.select().where(User.active == True).order_by(User.username)

Tweet のすべてのカラムと親モデル User のすべてのカラムを選択する例。user 外部キーが Tweet インスタンスでアクセスされると、追加のクエリは必要ありません（詳細は N+1 を参照してください）。

query = (Tweet
         .select(Tweet, User)
         .join(User)
         .order_by(Tweet.created_date.desc()))

for tweet in query:
    print(tweet.user.username, '->', tweet.content)

主キーのみを選択するサブクエリの例

inactive_users = User.select().where(User.active == False)

# Here, instead of defaulting to all columns, Peewee will default
# to only selecting the primary key.
Tweet.delete().where(Tweet.user.in_(inactive_users)).execute()

classmethod update([__data=None[, **update]])

パラメーター

• __data (dict) – フィールドと値のdict。

• update – フィールド名と値のマッピング。

UPDATE クエリを作成します。

登録が期限切れになったユーザーを非アクティブにマークする例

q = (User
     .update({User.active: False})
     .where(User.registration_expired == True))
q.execute()  # Execute the query, returning number of rows updated.

アトミック更新を示す例

q = (PageView
     .update({PageView.count: PageView.count + 1})
     .where(PageView.url == url))
q.execute()  # Execute the query.

注記

UPDATE クエリが実行されると、変更された行数が返されます。

classmethod insert([__data=None[, **insert]])

パラメーター

• __data (dict) – 挿入するフィールドと値のdict。

• insert – フィールド名と値のマッピング。

INSERT クエリを作成します。

データベースに新しい行を挿入します。モデルのフィールドにデフォルト値がある場合、insert ディクショナリでフィールドを明示的に設定しない限り、これらの値が使用されます。

新しいユーザーを作成する例

q = User.insert(username='admin', active=True, registration_expired=False)
q.execute()  # perform the insert.

Field オブジェクトをキーとして使用することもできます。

new_id = User.insert({User.username: 'admin'}).execute()

フィールドの1つにデフォルト値があり、そのフィールドがinsertパラメーターで指定されていない場合、デフォルト値が使用されます。

class User(Model):
    username = CharField()
    active = BooleanField(default=True)

# This INSERT query will automatically specify `active=True`:
User.insert(username='charlie')

注記

自動インクリメントする主キーを持つテーブルに対してINSERTクエリを実行すると、新しい行の主キーが返されます。

classmethod insert_many(rows[, fields=None])

パラメーター

• rows – 挿入する行を生成するイテラブル。

• fields (list) – 挿入されるフィールドのリスト。

戻り値

変更された行数（注を参照）。

複数のデータ行を挿入します。

rows パラメーターは、ディクショナリまたはタプルのシーケンスを生成するイテラブルでなければなりません。タプルの値の順序は、fields引数で指定されたフィールドに対応します。insert() と同様に、ディクショナリに指定されていないフィールドには、存在する場合はデフォルト値が使用されます。

注記

バルク挿入の性質上、各行には同じフィールドが含まれている必要があります。次の例は動作しません。

Person.insert_many([
    {'first_name': 'Peewee', 'last_name': 'Herman'},
    {'first_name': 'Huey'},  # Missing "last_name"!
]).execute()

複数のユーザーを挿入する例

data = [
    ('charlie', True),
    ('huey', False),
    ('zaizee', False)]
query = User.insert_many(data, fields=[User.username, User.is_admin])
query.execute()

ディクショナリを使用した同等の例

data = [
    {'username': 'charlie', 'is_admin': True},
    {'username': 'huey', 'is_admin': False},
    {'username': 'zaizee', 'is_admin': False}]

# Insert new rows.
User.insert_many(data).execute()

rows パラメーターは任意のイテラブルなので、ジェネレーターを使用することもできます。

def get_usernames():
    for username in ['charlie', 'huey', 'peewee']:
        yield {'username': username}
User.insert_many(get_usernames()).execute()

警告

SQLite を使用している場合、バルク挿入を利用するには、SQLite ライブラリのバージョンが 3.7.11 以降である必要があります。

注記

SQLite には、ステートメントあたりのバインド変数のデフォルト制限があります。この制限はコンパイル時または実行時に変更できますが、**実行時に変更する場合、デフォルト制限よりも低い値のみを指定できます。**

詳細については、次の SQLite ドキュメントを参照してください。

• 最大変数数の制限

• 実行時制限の変更

• SQLite コンパイル時フラグ

注記

デフォルトの戻り値は変更された行数です。ただし、Postgres を使用している場合、Peewee はデフォルトで挿入された行の主キーを生成するカーソルを返します。Postgres でこの機能を無効にするには、as_rowcount() を使用します。

classmethod insert_from(query, fields)

パラメーター

• query (Select) – データソースとして使用する SELECT クエリ。

• fields – データを挿入するフィールド。

戻り値

変更された行数（注を参照）。

SELECT クエリをデータソースとして使用してデータを挿入します。このAPIは、INSERT INTO … SELECT FROM … の形式のクエリに使用します。

非正規化のためにテーブル間でデータを挿入する例

source = (User
          .select(User.username, fn.COUNT(Tweet.id))
          .join(Tweet, JOIN.LEFT_OUTER)
          .group_by(User.username))

UserTweetDenorm.insert_from(
    source,
    [UserTweetDenorm.username, UserTweetDenorm.num_tweets]).execute()

注記

デフォルトの戻り値は変更された行数です。ただし、Postgres を使用している場合、Peewee はデフォルトで挿入された行の主キーを生成するカーソルを返します。Postgres でこの機能を無効にするには、as_rowcount() を使用します。

classmethod replace([__data=None[, **insert]])

パラメーター

• __data (dict) – 挿入するフィールドと値のdict。

• insert – フィールド名と値のマッピング。

競合解決に REPLACE を使用する INSERT クエリを作成します。

例については、Model.insert() を参照してください。

classmethod replace_many(rows[, fields=None])

パラメーター

• rows – 挿入する行を生成するイテラブル。

• fields (list) – 挿入されるフィールドのリスト。

競合解決に REPLACE を使用する複数のデータ行を挿入します。

例については、Model.insert_many() を参照してください。

classmethod raw(sql, *params)

パラメーター

• sql (str) – 実行するSQLクエリ。

• params – クエリのパラメーター。

SQL クエリを直接実行します。

User テーブルから行を選択する例

q = User.raw('select id, username from users')
for user in q:
    print(user.id, user.username)

注記

一般的に、raw の使用は、SELECT クエリを大幅に最適化できる場合に限定されます。モデルのインスタンスを返すため、SELECT クエリに役立ちます。

classmethod delete()

DELETEクエリを作成します。

非アクティブユーザーの全削除を示す例

q = User.delete().where(User.active == False)
q.execute()  # Remove the rows, return number of rows removed.

警告

このメソッドはテーブル全体の削除を実行します。単一インスタンスを削除するには、Model.delete_instance()を参照してください。

classmethod create(**query)

パラメーター

query – フィールド名と値のマッピング。

テーブルに新しい行をINSERTし、対応するモデルインスタンスを返します。

ユーザーの作成を示す例（データベースに行が追加されます）

user = User.create(username='admin', password='test')

注記

create()メソッドは、インスタンス化と保存の省略記法です。

classmethod bulk_create(model_list[, batch_size=None])

パラメーター

• model_list (iterable) – 未保存のModelインスタンスのリストまたはその他のiterable。

• batch_size (int) – INSERTする行のバッチ数。指定しない場合、すべてのモデルが単一のクエリで挿入されます。

戻り値

戻り値なし。

データベースに複数の未保存モデルインスタンスを効率的にINSERTします。insert_many()は、行データとして辞書またはリストのリストを受け入れるのに対し、このメソッドは未保存モデルインスタンスのリストを受け入れます。

例

# List of 10 unsaved users.
user_list = [User(username='u%s' % i) for i in range(10)]

# All 10 users are inserted in a single query.
User.bulk_create(user_list)

バッチ処理

user_list = [User(username='u%s' % i) for i in range(10)]

with database.atomic():
    # Will execute 4 INSERT queries (3 batches of 3, 1 batch of 1).
    User.bulk_create(user_list, batch_size=3)

警告

• 新しく作成されたモデルの主キー値は、RETURNING句をサポートするPostgresqlを使用している場合にのみ設定されます。

• SQLiteは一般的にクエリのバインドパラメーターに制限があるため、最大バッチサイズは、パラメーター制限/フィールド数になります。この制限は、通常、Sqlite < 3.32.0では999、新しいバージョンでは32766です。

• バッチサイズが指定されている場合、Database.atomic()を使用してトランザクションまたはセーブポイントで呼び出しをラップすることを強く推奨します。そうでない場合、途中でバッチでエラーが発生すると、データベースが不整合な状態になる可能性があります。

classmethod bulk_update(model_list, fields[, batch_size=None])

パラメーター

• model_list (iterable) – Modelインスタンスのリストまたはその他のiterable。

• fields (list) – 更新するフィールドのリスト。

• batch_size (int) – INSERTする行のバッチ数。指定しない場合、すべてのモデルが単一のクエリで挿入されます。

戻り値

更新された行の総数。

複数のモデルインスタンスを効率的にUPDATEします。

例

# First, create 3 users.
u1, u2, u3 = [User.create(username='u%s' % i) for i in (1, 2, 3)]

# Now let's modify their usernames.
u1.username = 'u1-x'
u2.username = 'u2-y'
u3.username = 'u3-z'

# Update all three rows using a single UPDATE query.
User.bulk_update([u1, u2, u3], fields=[User.username])

これは次のSQLを実行します。

UPDATE "users" SET "username" = CASE "users"."id"
    WHEN 1 THEN "u1-x"
    WHEN 2 THEN "u2-y"
    WHEN 3 THEN "u3-z" END
WHERE "users"."id" IN (1, 2, 3);

大量のオブジェクトを更新する必要がある場合は、batch_sizeを指定し、操作をトランザクションでラップすることを強くお勧めします。

with database.atomic():
    User.bulk_update(user_list, fields=['username'], batch_size=50)

警告

• SQLiteは一般的にクエリのバインドパラメーターに制限があります。この制限は、通常、Sqlite < 3.32.0では999、新しいバージョンでは32766です。

• バッチサイズが指定されている場合、Database.atomic()を使用してトランザクションまたはセーブポイントで呼び出しをラップすることを強く推奨します。そうでない場合、途中でバッチでエラーが発生すると、データベースが不整合な状態になる可能性があります。

classmethod get(*query, **filters)

パラメーター

• query – 0個以上のExpressionオブジェクト。

• filters – Djangoスタイルのフィルターのフィールド名と値のマッピング。

例外

DoesNotExist

戻り値

指定されたフィルターに一致するモデルインスタンス。

指定されたフィルターに一致する単一のモデルインスタンスを取得します。モデルが返されない場合、DoesNotExistが送出されます。

user = User.get(User.username == username, User.active == True)

このメソッドはSelectQueryからも公開されていますが、パラメーターは受け取りません。

active = User.select().where(User.active == True)
try:
    user = active.where(
        (User.username == username) &
        (User.active == True)
    ).get()
except User.DoesNotExist:
    user = None

注記

get()メソッドは、制限を1に設定した選択の省略記法です。一致する行が見つからない場合に例外を送出するという追加の動作があります。複数の行が見つかった場合、データベースカーソルによって返される最初の行が使用されます。

classmethod get_or_none(*query, **filters)

Model.get()と同じですが、指定されたフィルターに一致するモデルがない場合はNoneを返します。

classmethod get_by_id(pk)

パラメーター

pk – 主キー値。

主キーによる検索を指定してModel.get()を呼び出すための省略記法です。指定された主キー値を持つインスタンスが存在しない場合は、DoesNotExistを送出します。

例

user = User.get_by_id(1)  # Returns user with id = 1.

classmethod set_by_id(key, value)

パラメーター

• key – 主キー値。

• value (dict) – 更新するフィールドと値のマッピング。

指定された主キーでデータを更新するための省略記法です。指定された主キーを持つ行が存在しない場合、例外は送出されません。

例

# Set "is_admin" to True on user with id=3.
User.set_by_id(3, {'is_admin': True})

classmethod delete_by_id(pk)

パラメーター

pk – 主キー値。

指定された主キーを持つ行を削除するための省略記法です。指定された主キーを持つ行が存在しない場合、例外は送出されません。

classmethod get_or_create(**kwargs)

パラメーター

• kwargs – フィールド名と値のマッピング。

• defaults – 新しい行を作成する場合に使用するデフォルト値。

戻り値

Modelインスタンスと、新しいオブジェクトが作成されたかどうかを示すブール値のタプル。

指定されたフィルターに一致する行を取得しようとします。一致する行が見つからない場合は、新しい行を作成します。

警告

このメソッドを使用すると、競合状態が発生する可能性があります。

get_or_createを使用しない例

# Without `get_or_create`, we might write:
try:
    person = Person.get(
        (Person.first_name == 'John') &
        (Person.last_name == 'Lennon'))
except Person.DoesNotExist:
    person = Person.create(
        first_name='John',
        last_name='Lennon',
        birthday=datetime.date(1940, 10, 9))

get_or_createを使用した同等のコード

person, created = Person.get_or_create(
    first_name='John',
    last_name='Lennon',
    defaults={'birthday': datetime.date(1940, 10, 9)})

classmethod filter(*dq_nodes, **filters)

パラメーター

• dq_nodes – 0個以上のDQオブジェクト。

• filters – Djangoスタイルのフィルター。

戻り値

ModelSelect クエリ。

get_id()

戻り値

モデルインスタンスの主キー。

save([force_insert=False[, only=None]])

パラメーター

• force_insert (bool) – INSERTクエリを強制します。

• only (list) – 指定されたFieldインスタンスのみを保存します。

戻り値

変更された行数。

モデルインスタンスのデータを保存します。デフォルトでは、主キー値が存在すると、UPDATEクエリが実行されます。

モデルインスタンスの保存を示す例

user = User()
user.username = 'some-user'  # does not touch the database
user.save()  # change is persisted to the db

dirty_fields

変更されたフィールドのリストを返します。

戻り値の型

リスト

注記

変更されたフィールドだけを永続化したい場合は、model.save(only=model.dirty_fields)を呼び出すことができます。

モデルの変更されたフィールドだけを常に保存したい場合は、Metaオプションonly_save_dirty = Trueを使用できます。次に、Model.save()を呼び出すたびに、デフォルトで変更されたフィールドのみが保存されます。

class Person(Model):
    first_name = CharField()
    last_name = CharField()
    dob = DateField()

    class Meta:
        database = db
        only_save_dirty = True

警告

Peeweeは、モデルインスタンスでフィールド属性が設定されたときに、フィールドが「変更済み」かどうかを判断します。辞書インスタンスなどの変更可能な値を含むフィールドがあり、その辞書が変更された場合、Peeweeはその変更を認識しません。

is_dirty()

フィールドが手動で設定されたかどうかを示すブール値を返します。

delete_instance([recursive=False[, delete_nullable=False]])

パラメーター

• recursive (bool) – 関連モデルを削除します。

• delete_nullable (bool) – NULL外部キーを持つ関連モデルを削除します。Falseの場合、NULL可能なリレーションはNULLに設定されます。

指定されたインスタンスを削除します。削除時にカスケード設定されている外部キーは自動的に削除されます。よりプログラム的な制御を行うには、recursive=True を指定できます。これにより、NULL 許容ではない関連モデルが削除され（NULL 許容のモデルは NULL に設定されます）、NULL 許容に関わらずすべての依存関係を削除する場合は、delete_nullable=True を設定します。

例

some_obj.delete_instance()  # it is gone forever

classmethod bind(database[, bind_refs=True[, bind_backrefs=True]])

パラメーター

• database (Database) – バインドするデータベース。

• bind_refs (bool) – 関連モデルをバインドします。

• bind_backrefs (bool) – バックリファレンス関連モデルをバインドします。

モデル（および指定されたリレーション）を指定されたデータベースにバインドします。

参照：Database.bind()。

classmethod bind_ctx(database[, bind_refs=True[, bind_backrefs=True]])

bind() と似ていますが、ラップされたブロックの期間中のみモデルをバインドするコンテキストマネージャーを返します。

参照：Database.bind_ctx()。

classmethod table_exists()

戻り値

テーブルが存在するかどうかを示すブール値。

classmethod create_table([safe=True[, **options]])

パラメーター

safe (bool) – True に設定されている場合、CREATE TABLE クエリに IF NOT EXISTS 句が含まれます。

モデルのテーブル、インデックス、制約、シーケンスを作成します。

例

with database:
    SomeModel.create_table()  # Execute the create table query.

classmethod drop_table([safe=True[, **options]])

パラメーター

safe (bool) – True に設定されている場合、DROP TABLE クエリに IF EXISTS 句が含まれます。

モデルのテーブルを削除します。

truncate_table([restart_identity=False[, cascade=False]])

パラメーター

• restart_identity (bool) – IDシーケンスを再開します（PostgreSQLのみ）。

• cascade (bool) – 関連テーブルも切り詰めます（PostgreSQLのみ）。

モデルのテーブルからすべての行を削除します。

classmethod index(*fields[, unique=False[, safe=True[, where=None[, using=None[, name=None]]]]])

パラメーター

• fields – インデックスを作成するフィールド。

• unique (bool) – インデックスがUNIQUEかどうか。

• safe (bool) – IF NOT EXISTS句を追加するかどうか。

• where (Expression) – インデックスのオプションのWHERE句。

• using (str) – インデックスアルゴリズム。

• name (str) – オプションのインデックス名。

モデルにインデックスを宣言するための簡潔なメソッド。ModelIndex インスタンスの宣言をラップします。

例

class Article(Model):
    name = TextField()
    timestamp = TimestampField()
    status = IntegerField()
    flags = BitField()

    is_sticky = flags.flag(1)
    is_favorite = flags.flag(2)

# CREATE INDEX ... ON "article" ("name", "timestamp" DESC)
idx = Article.index(Article.name, Article.timestamp.desc())

# Be sure to add the index to the model:
Article.add_index(idx)

# CREATE UNIQUE INDEX ... ON "article" ("timestamp" DESC, "flags" & 2)
# WHERE ("status" = 1)
idx = (Article
       .index(Article.timestamp.desc(),
              Article.flags.bin_and(2),
              unique=True)
       .where(Article.status == 1))

# Add index to model:
Article.add_index(idx)

classmethod add_index(*args, **kwargs)

パラメーター

• args – ModelIndex インスタンス、インデックスを作成するフィールド、またはインデックス作成のための SQL を含む SQL インスタンス。

• kwargs – ModelIndex コンストラクタに渡されるキーワード引数。

モデルの定義にインデックスを追加します。

注記

このメソッドは、データベースにインデックスを実際に作成するものではありません。代わりに、インデックス定義をモデルのメタデータに追加するため、後続の create_table() の呼び出しで新しいインデックス（テーブルと共に）が作成されます。

例

class Article(Model):
    name = TextField()
    timestamp = TimestampField()
    status = IntegerField()
    flags = BitField()

    is_sticky = flags.flag(1)
    is_favorite = flags.flag(2)

# CREATE INDEX ... ON "article" ("name", "timestamp") WHERE "status" = 1
idx = Article.index(Article.name, Article.timestamp).where(Article.status == 1)
Article.add_index(idx)

# CREATE UNIQUE INDEX ... ON "article" ("timestamp" DESC, "flags" & 2)
ts_flags_idx = Article.index(
    Article.timestamp.desc(),
    Article.flags.bin_and(2),
    unique=True)
Article.add_index(ts_flags_idx)

# You can also specify a list of fields and use the same keyword
# arguments that the ModelIndex constructor accepts:
Article.add_index(
    Article.name,
    Article.timestamp.desc(),
    where=(Article.status == 1))

# Or even specify a SQL query directly:
Article.add_index(SQL('CREATE INDEX ...'))

dependencies([search_nullable=False])

パラメーター

search_nullable (bool) – NULL 許容の外部キーを介して関連付けられたモデルを検索します。

戻り値の型

クエリと外部キーフィールドを生成するジェネレーター式。

依存モデルのクエリリストを生成します。クエリと対応する外部キーフィールドを含む 2 要素のタプルを生成します。モデルの依存関係（削除した場合に孤立する可能性のあるもの）を検索する際に役立ちます。

__iter__()

戻り値

指定されたクラスの ModelSelect。

モデルのすべてのインスタンスを反復処理するための便利な関数。

例

Setting.insert_many([
    {'key': 'host', 'value': '192.168.1.2'},
    {'key': 'port': 'value': '1337'},
    {'key': 'user': 'value': 'nuggie'}]).execute()

# Load settings from db into dict.
settings = {setting.key: setting.value for setting in Setting}

__len__()

戻り値

テーブル内の行数。

例

n_accounts = len(Account)

# Is equivalent to:
n_accounts = Account.select().count()

class ModelAlias(model[, alias=None])

パラメーター

• model (Model) – 参照するモデルクラス。

• alias (str) – （オプション）エイリアスの名前。

クエリ内でモデルへの別々の参照を提供します。

class ModelSelect(model, fields_or_models)

パラメーター

• model (Model) – 選択するモデルクラス。

• fields_or_models – 選択するフィールドまたはモデルクラスのリスト。

SELECT クエリのモデル固有の実装。

switch([ctx=None])

パラメーター

ctx – 結合された Model、ModelAlias、サブクエリ、またはその他のオブジェクト。

結合コンテキストを切り替えます。これは、join() の後続の呼び出しが結合されるソースです。単一のテーブルに対する複数の結合を指定するために使用されます。

ctx が指定されていない場合、クエリのモデルが使用されます。

次の例では、tweet を選択し、user と tweet-flag の両方に結合します。

sq = Tweet.select().join(User).switch(Tweet).join(TweetFlag)

# Equivalent (since Tweet is the query's model)
sq = Tweet.select().join(User).switch().join(TweetFlag)

objects([constructor=None])

パラメーター

constructor – コンストラクタ（モデルインスタンスを返すのがデフォルト）。

指定されたコンストラクタを使用して作成されたオブジェクトとして結果行を返します。デフォルトの動作は、モデルインスタンスを作成することです。

注記

このメソッドは、複数のソース/モデルからフィールドデータを選択する場合に、クエリ対象のモデルの属性としてすべてのデータを使用できるようにするために使用できます（結合されたモデルインスタンスのグラフを作成する代わりに）。非常に複雑なクエリの場合、特に大規模な結果セットを反復処理する場合、パフォーマンスにプラスの効果があります。

同様に、dicts()、tuples()、またはnamedtuples() を使用して、さらにパフォーマンスを向上させることができます。

join(dest[, join_type='INNER'[, on=None[, src=None[, attr=None]]]])

パラメーター

• dest – Model、ModelAlias、Select クエリ、または結合するその他のオブジェクト。

• join_type (str) – 結合タイプ。デフォルトはINNER。

• on – 結合述語または結合するForeignKeyField。

• src – 結合のソースを明示的に指定します。指定しない場合は、現在の結合コンテキストが使用されます。

• attr – 結合されたモデルから列を投影する際に使用する属性。

別のテーブルのようなオブジェクトとの結合。

結合の種類は次のいずれかです。

• JOIN.INNER

• JOIN.LEFT_OUTER

• JOIN.RIGHT_OUTER

• JOIN.FULL

• JOIN.FULL_OUTER

• JOIN.CROSS

「admin」ユーザーによって作成されたツイートのみに制限するために、ツイートを選択し、ユーザーに結合する例

sq = Tweet.select().join(User).where(User.is_admin == True)

特定の外部キーフィールドに結合してユーザーを選択する例。実際の使用方法については、サンプルアプリケーションを参照してください。

sq = User.select().join(Relationship, on=Relationship.to_user)

外部キー、結合、モデル間の関係の詳細については、Relationships and Joinsを参照してください。

join_from(src, dest[, join_type='INNER'[, on=None[, attr=None]]])

パラメーター

• src – 結合のソース。

• dest – 結合先のテーブル。

モデルに依存しないjoin()と同じパラメーター順序を使用します。結合ソースの指定が必要なため、結合コンテキストをバイパスします。

filter(*args, **kwargs)

パラメーター

• args – 0個以上のDQオブジェクト。

• kwargs – Djangoスタイルのキーワード引数フィルター。

Djangoスタイルのフィルターを使用してWHERE句を表現します。結合は外部キーフィールドをチェーンすることで実行できます。サポートされている演算子は次のとおりです。

• eq - 等しい

• ne - 等しくない

• lt、lte - より小さい、より小さいか等しい

• gt、gte - より大きい、より大きいか等しい

• in - 値のセットに含まれる

• is - IS（例：IS NULL）

• like、ilike - LIKEおよびILIKE（大文字と小文字を区別しない）

• regexp - 正規表現の一致

例

# Get all tweets by user with username="peewee".
q = Tweet.filter(user__username='peewee')

# Get all posts that are draft or published, and written after 2023.
q = Post.filter(
    (DQ(status='draft') | DQ(status='published')),
    timestamp__gte=datetime.date(2023, 1, 1))

prefetch(*subqueries[, prefetch_type=PREFETCH_TYPE.WHERE])

パラメーター

• subqueries – プリフェッチするModelクラスまたは選択クエリのリスト。

• prefetch_type – サブクエリに使用するクエリタイプ。

戻り値

選択されたリレーションがプリフェッチされたモデルのリスト。

指定された追加のリソースをプリフェッチしてクエリを実行します。

プリフェッチタイプは次のいずれかになります。

• PREFETCH_TYPE.WHERE

• PREFETCH_TYPE.JOIN

スタンドアロン関数prefetch()も参照してください。

例

# Fetch all Users and prefetch their associated tweets.
query = User.select().prefetch(Tweet)
for user in query:
    print(user.username)
    for tweet in user.tweets:
        print('  *', tweet.content)

注記

prefetchはモデルのグラフを再構築する必要があるため、関連オブジェクトを正しくマッピングできるように、関連モデルの外部キー/主キーが選択されていることを確認する必要があります。

prefetch(sq, *subqueries[, prefetch_type=PREFETCH_TYPE.WHERE])

パラメーター

• sq – 開始点として使用するクエリ。

• subqueries – 1つ以上のモデルまたはModelSelectクエリを事前にフェッチします。

• prefetch_type – サブクエリに使用するクエリタイプ。

戻り値

選択されたリレーションがプリフェッチされたモデルのリスト。

1対多の関係が存在する場合、複数のテーブルを効率的にクエリできるように、関連オブジェクトを事前にフェッチします。プリフェッチタイプはサブクエリの構築方法を変更しますが、使用中のデータベースエンジンによっては望ましい場合があります。

プリフェッチタイプは次のいずれかになります。

• PREFETCH_TYPE.WHERE

• PREFETCH_TYPE.JOIN

たとえば、多対1の関係を効率的にクエリすることは簡単です。

query = (Tweet
         .select(Tweet, User)
         .join(User))
for tweet in query:
    # Looking up tweet.user.username does not require a query since
    # the related user's columns were selected.
    print(tweet.user.username, '->', tweet.content)

逆を効率的に行い、ユーザーとそのツイートをクエリするには、prefetchを使用できます。

query = User.select()
for user in prefetch(query, Tweet):
    print(user.username)
    for tweet in user.tweets:  # Does not require additional query.
        print('    ', tweet.content)

注記

prefetchはモデルのグラフを再構築する必要があるため、関連オブジェクトを正しくマッピングできるように、関連モデルの外部キー/主キーが選択されていることを確認する必要があります。

クエリビルダー内部

class AliasManager

SELECTクエリ内のSourceオブジェクトに割り当てられたエイリアスを管理し、単一クエリで複数のソースが使用されている場合のあいまいな参照を回避します。

add(source)

現在のスコープでAliasManagerの内部レジストリにソースを追加します。エイリアスは、次のスキーム（インデントの各レベルは新しいスコープを表します）を使用して自動的に生成されます。

パラメーター

source (Source) – マネージャーに新しいソースを認識させます。ソースが既に追加されている場合、呼び出しはノーオペレーションです。

get(source[, any_depth=False])

現在のスコープでソースのエイリアスを返します。ソースにエイリアスがない場合、使用可能な次のエイリアスが割り当てられます。

パラメーター

source (Source) – エイリアスを取得するソース。

戻り値

ソースに既に割り当てられているエイリアス、または使用可能な次のエイリアス。

戻り値の型

str

__setitem__(source, alias)

現在のスコープでソースのエイリアスを手動で設定します。

パラメーター

source (Source) – エイリアスを設定するソース。

push()

スタックに新しいスコープをプッシュします。

pop()

スタックからスコープをポップします。

class State(scope[, parentheses=False[, subquery=False[, **kwargs]]])

特定のスコープの状態を表す軽量オブジェクト。SQL生成中に、Contextによってアクセスされた各オブジェクトは状態を検査できます。Stateクラスにより、Peeweeは次のようなことができます。

• フィールドタイプまたはSQL式に共通のインターフェースを使用しますが、ベンダー固有のデータ型または演算子を使用します。

• scopeの値に応じて、Columnインスタンスを完全修飾属性、名前付きエイリアスなどにコンパイルします。

• かっこを適切に使用します。

パラメーター

• scope (int) – 状態がアクティブな間に適用されるスコープルール。

• parentheses (bool) – 含まれるSQLをかっこで囲みます。

• subquery (bool) – 現在の状態が外部クエリのサブクエリであるかどうか。

• kwargs (dict) – 現在の状態に適用する任意の設定。

class Context(**settings)

Peewee構造をパラメーター化されたSQLクエリに変換します。

Peewee構造はすべて__sql__メソッドを実装する必要があります。このメソッドは、SQL生成中にContextクラスによって呼び出されます。__sql__メソッドは、単一のパラメーターとしてContextインスタンスを受け取ります。これにより、再帰的下降とスコープと状態のイントロスペクションが可能になります。

scope

現在アクティブなスコープルールを返します。

parentheses

現在の状態が括弧で囲まれているかどうかを返します。

subquery

現在の状態が別のクエリの子ノードかどうかを返します。

scope_normal([**kwargs])

デフォルトのスコープ。ソースはエイリアスで、列はソースからのドット区切りパスで参照されます。

scope_source([**kwargs])

ソースを定義する際に使用されるスコープ（例：SELECTクエリの列リストとFROM句）。このスコープは、ソースの完全修飾名を定義し、エイリアスを割り当てるために使用されます。

scope_values([**kwargs])

UPDATE、INSERT、またはDELETEクエリで使用されるスコープ。エイリアスでソースを参照する代わりに、直接参照します。同様に、単一のテーブルがあるため、列をドット区切りパスで参照する必要はありません。

scope_cte([**kwargs])

共通テーブル式（CTE）の内容を生成する際に使用されるスコープ。WITH文の後、CTEの定義を生成する際に使用されます（単なる参照ではなく）。

scope_column([**kwargs])

列のSQLを生成する際に使用されるスコープ。列が正しいエイリアスでレンダリングされるようにします。サブセレクトの内部投影を参照する場合、Peeweeは列の「ソース」として完全なSELECTクエリをレンダリングしていたため（クエリのエイリアス + . + 列ではなく）必要になりました。このスコープにより、エイリアスのみが必要な場合に、完全なクエリをレンダリングするのを回避できます。

sql(obj)

コンポーザブルなNodeオブジェクト、サブコンテキスト、またはその他のオブジェクトをクエリのASTに追加します。整数、文字列、浮動小数点数などのPythonの値は、パラメーター化された値として扱われます。

戻り値

更新されたContextオブジェクト。

literal(keyword)

文字列リテラルを現在のクエリのASTに追加します。

戻り値

更新されたContextオブジェクト。

parse(node)

パラメーター

node (Node) – Nodeサブクラスのインスタンス。

戻り値

(sql、パラメーター)からなる2要素のタプル。

与えられたノードをSQL ASTに変換し、SQLクエリとパラメーターからなる2要素のタプルを返します。

query()

戻り値

コンテキストの(sql、パラメーター)からなる2要素のタプル。

定数とヘルパー

class Proxy

別のオブジェクトのプロキシまたはプレースホルダーを作成します。

initialize(obj)

パラメーター

obj – プロキシするオブジェクト。

プロキシを指定されたオブジェクトにバインドします。その後、プロキシでのすべての属性検索とメソッド呼び出しは、指定されたオブジェクトに送信されます。

登録されているコールバックがすべて呼び出されます。

attach_callback(callback)

パラメーター

callback – 単一のパラメーター（バインドされたオブジェクト）を受け取る関数。

戻り値

self

プロキシが初期化されたときに実行されるコールバックを追加します。

class DatabaseProxy

Databaseインスタンスのプレースホルダーとして使用できるProxyサブクラス。

使用方法の詳細については、データベースの動的定義を参照してください。

chunked(iterable, n)

パラメーター

• iterable – チャンク化されるデータのソースとなるイテラブル。

• n (int) – チャンクサイズ。

戻り値

ソースデータのn長さのチャンクを生成する新しいイテラブル。

大規模なデータリストをより小さなチャンクに分割するための効率的な実装。

使用方法

it = range(10)  # An iterable that yields 0...9.

# Break the iterable into chunks of length 4.
for chunk in chunked(it, 4):
    print(', '.join(str(num) for num in chunk))

# PRINTS:
# 0, 1, 2, 3
# 4, 5, 6, 7
# 8, 9