.. meta:: :keywords: web2py, framework, DAL, データベース抽象化レイヤ, Field class, Fieldクラス .. currentmodule:: dal .. _class_field: Field ===== Filedはデータベーステーブルのフィールドに関するクラスです。 Fieldクラスのインスタンス生成によって、フィールド定義が可能です。この他にFieldクラスは :ref:`class_Expression` クラスを継承しているため、 Fieldインスタンスと共にExpressionクラスのメソッドが使用可能です。 参考: `Record Representation `_ | `レコードの表現 `_ .. include:: class_diagrams/field.html インスタンス化 -------------- Fieldインスタンスの生成は、Fieldクラスのコンストラクタを使用します。また既に定義されているテーブルのフィールドの場合は、 **db.テーブル名.フィールド名** でFieldインスタンスにアクセスできます [#f1]_ 。 .. topic:: 【 Fieldインスタンスの生成とアクセス 】 * 生成・・・・・・ **コンストラクタ** を使用します。 * アクセス・・・定義されているテーブルのフィールドへは **db.テーブル名.フィールド名** でアクセス可能です。 :: >>> field = db.person.name # personテーブルのnameフィールドの Fieldインスタンス \  .. class:: Field() -> Fieldインスタンス コンストラクタはフィールド定義を行います。 :: db.define_table('item', Field('name','string',length=256), Field('unit_cost','decimal(10,6)')) db.define_table('inventory', Field('item', db.item), Field('actual','decimal(10,2)'), Field('reserved','decimal(10,2)')) :param name: フィールド名 :param type: フィールド型 :param length: フィール長 :param default: デフォルト値 :param required: 挿入時(DAL)の必須設定 :param requires: SQLFORMでのバリデータ設定 :param ondelete: レコード削除時の動作設定 :param notnull: Null値の禁止設定 :param unique: ユニーク値の設定 :param widget: ウィジットの設定 :param label: フィールドラベルの値 :param comment: フィールドのコメント値 :param writable: フォームの編集設定 :param readable: フォームの表示設定 :param update: 更新時のデフォルト値 :param compute: 挿入・更新時の関数設定 :param represent: 読み出し時の関数設定 :param uploadfield: upload型でのblobフィールドの設定 :param uploadseparate: upload型でのサブ・フォルダ設定 :param authorize: upload型のアクセスコントロール設定 :param autodelete: upload型の参照レコード削除時のファイル削除設定 :return: Fieldインスタンス 以下パラメータの詳細な説明を行いますが、一部のパラメータはデータベース(DAL)向けではなく、SQLFORM向けだけの設定です。 このためSQLFORMの専用パラメータの名前の横には、 *(SQLFORM専用)* と記述するようにします。 name フィールド名を文字列で指定します。 .. _param_type: type 次のフィールドタイプを文字列で指定できます。 ``string`` , ``text`` , ``boolean`` , ``integer`` , ``double`` , ``decimal(n,m)`` ``date`` , ``time`` , ``datetime`` , ``password`` , ``blob`` , ``upload`` ``reference `` , ``list:string`` , ``list:integer`` , ``list:reference
`` ``json`` , ``bigint`` , ``big-id`` , ``big-reference`` * ``decimal(n,m)`` は10進数型です。nは全体の桁数、mには小数点以下の桁数を設定します。SQLiteではdobuleとして扱われます。 * ``blob`` はバイナリデータを格納できます。web2pyは格納時にbase64でエンコード、取り出し時にデコードします。 * ``upload`` はアップロードファイル型です。アップロードファイルはサーバのファイルシステムに保存されます。 ファイルシステムではなくBlobフィールドに保存する設定も可能です。GAEでは何も設定しなくても Datasore に保存します。 .. _field_reference: * ``reference
`` は他テーブルへの参照フィールド型です。次のように、referenceキーワードで指定します。 :: Field('owner_id', 'reference person') referenceキーワードの代わりに、Tableインスタンスを指定しても同じように動作します。 :: Field('owner_id', db.person) Tableインスタンスを使った参照フィールドの設定では、 :ref:`table_relation` と :ref:`self_reference` も参照ください。 .. _field_list: * ``list:string`` , ``list:integer`` , ``list:reference
`` これらのリストフィールドは GAE の Datastore では ListProperty や StringListProperty といったフィールドに対応しています。 RDBMS でないタイプのデータベースが持つ機能ですが、web2py ではこれらのフィールドも RDBMS に対 して利用することが可能です。 リストフィールドのデータは RDBMS では、textフィールドに '|' の区切り文字で格納されます。 :ref:`list_relation` も参照ください。 * リストフィールドの検索は、 :meth:`~dal.Expression.contains` メソッドを使用します。 * ``list:reference
`` はデフォルトでは次のバリデータが設定されています。 :: IS_IN_DB(db,’
.id’,multiple=True) これはフォームで複数選択可能なドロップボックを表示します。 * ``list:string`` , ``list:integer`` デフォルトではバリデータは設定されていません( :ref:`default_field_validators` )。 フォームで利用する場合は、IS_IN_SET か IS_IN_DB を設定する必要があります。 * ``json`` シリアル化されたJsonオブジェクトを保管します。 * ``big-id`` , ``big-reference`` は一部のデータベースでサポートされています。 :class:`~DAL` コンストラクタのパラメータ bigint_id を True で指定すれば、``id`` ``reference`` が ``big-id`` ``big-reference`` に変更されます。 length ``string`` , ``text`` , ``password`` , ``upload`` の最大フィールド長を設定します。設定しない場合はデフォルト値 を使用します。しかし後方互換性は保証されないので、設定することが推奨されています。 default デフォルト値。レコード挿入時にフィールドに値がないと、デフォルト値を設定します。 SQLFORMでは画面上にデフォルト値を表示します。 required True を設定するとフィールド値が要求されます。デフォルトは False です。 このパラメータは現在のところ、特に機能が実装されていないようです。このため、notnull パラメータを利用した方がよいでしょう。 requires (SQLFORM専用) バリデータもしくはバリデータのリストを設定します。この設定はSQLFORMのフィールドに対して動きます。 このオプションが無設定でも、フィールドタイプによってデフォルトで設定されるバリデータがあります( :ref:`default_field_validators` )。 参考: `Validators `_ | `バリデータ `_ .. _param_ondelete: ondelete 参照しているレコードを削除する設定です。デフォルトは CASCADE です。 CASCADE ではレコード削除時に、そのレコード を参照している全てのレコードを削除します。関連しているレコードを削除したくない場合、 NO ACTION を設定します。 notnull null値を許すかどうか設定します。デフォルトはFalseです。Trueに設定すると、フィールドにnull値の挿入を禁止します。 unique フィールド値のユニーク設定です。デフォルトはFalseです。Trueに設定すると、フィールド値がユニークなのを強制します。 widget (SQLFORM専用) 利用可能なウィジットの設定が可能です。デフォルトはNoneです。 label (SQLFORM専用) フィールドのラベルを設定します。デフォルトはNoneです。 comment (SQLFORM専用) フィールドのコメントを設定します。デフォルトはNoneです。 writable (SQLFORM専用) 編集可能かどうかの設定します。デフォルトはTrueです。Trueですとフォーム上で編集可能です。 readable (SQLFORM専用) 表示可能かどうかの設定します。デフォルトはTrueです。Trueですとフォーム上で表示可能です。 update 更新時のデフォルト値を設定できます。デフォルトはNoneです。 compute 挿入・更新時の関数を設定できます。デフォルトはNoneです。詳細は :ref:`compute` を参照ください。 represent レコード読み出し時の関数を設定できます。デフォルトはNoneです。詳細は :ref:`represent` を参照ください。 これ以降は ``upload`` フィールドに関するオプションです。 uploadfield アップロードファイルを ``blob`` タイプのデータベースフィールドに格納する場合に設定します。 このオプションに ``blob`` タイプのフィールドを指定します。詳細は参考を参照ください。 GAEではこの設定を行わなくても Datastore に格納します。 参考: `Upload Files in Database `_ | `データベース上でのファイルアップロード `_ uploadfolder ファイルを保存するフォルダを指定します。 指定しない場合、アプリケーションフォルダ下のuploadsフォルダになります。 例えば、次のように指定可能です。 :: uploadfolder=os.path.join(request.folder,'static/temp') この場合、web2py/applications/アプリケーション名/static/temp フォルダにアップロードファイルが保存されます。 uploadseparate アップローダファイルを保存先のサブフォルダに保存する場合に使用します。デフォルトはFalseです。 Trueにすると、アプリケーションフォルダのuploads下にサブフォルダを作成してファイルを保存します。 アプリケーションの稼働中は変更が反映されない。変更前に保存したファイルはアクセス不可能になるなど、 制約もあるようです(その場合はファイルを変更後の位置に移動させるなどが必要です)。 uploadfs Amazon S3、FTPサーバ、WebDAVなどの異なるファイルシステムにアップロドすることができます。 このオプションを指定する場合、 `PyFileSystem `_ が必要です。 デフォルトはNoneです。 authorize ``upload`` フィールドのアクセスコントロール用のオプションです。詳細は不明です。 autodelete アップロードファイルを参照するレコードを削除した場合、ファイルを削除するかどうかの設定です。 デフォルトはFalseです。Trueに設定すると削除します。 参考: `Record Representation `_ | `レコードの表現 `_ メソッド -------- メソッド説明用サンプルでは次のテーブルを利用します。 :: db.define_table('person', Field('name'), format='%(name)s') db.define_table('dog', Field('owner_id', db.person), Field('name')) .. method:: Field.count() -> Expressionインスタンス 自分自身を COUNT() 式中に設定する Expressionインスタンスを返します。 :meth:`~dal.Set.select` メソッドのパラメータなどに使用します。 SQLのCOUNT関数に変換されます。 :: >>> count = db.person.id.count() >>> for row in db(db.person.id==db.dog.owner_id).select(db.person.name, count,groupby=db.person.name): ... print row.person.name, row[count] Cosotama 1 Socepopa 2 >>> print db(db.person.id==db.dog.owner_id).select(db.person.name, db.person.id.count(), groupby=db.person.name) person.name,COUNT(person.id) Cosotama,1 Socepopa,2 >>> print db.person.id.count() COUNT(person.id) 戻り値 自分自身を COUNT() 式中に設定する Expressionインスタンスを返します。 .. method:: Field.formatter(value) -> 値 フィールドのバリデータを呼び出して、バリデータの表示フォーマットに反映した結果を返します。 :: db.define_table('person', Field('name'), Field('birthday', 'date', requires=IS_DATE(format='%Y/%m/%d')), format='%(name)s') personテーブルのbirthdayフィールドに、IS_DATEバリデータの表示設定がされている場合、formatterメソッドを利用して表示フォーマットを反映させることができます。 これは通常のフォーマットでの表示です。 :: >>> for row in db(db.person).select(): ... print row.name, row.birthday Pocomaco 2001-12-01 Satocoto 2002-01-20 Codatada 2001-08-12 バリデータで設定されているフォーマットでの表示です。 :: >>> for row in db(db.person).select(): ... print row.name, db.person.birthday.formatter(row.birthday) Pocomaco 2001/12/01 Satocoto 2002/01/20 Codatada 2001/08/12 value バリデータに渡す値です。 戻り値 バリデータの表示フォーマットに変換した値を返します。 .. method:: Field.validate(value) -> タプル値 フィールドのバリデータを呼び出して、結果を返します。 :: >>> print db.person.name.validate('test') ('test', None) >>> print db.person.name.validate('a'*513) ('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'enter from 0 to 512 characters') textタイプのバリデータは512文字以内なので、エラーが返される。 value バリデータする値を設定します。 戻り値 バリデータした値とエラー値を ``(value, error)`` のタプル型で返します。エラーがない場合は、エラー値は None になります。 属性 ---- 属性の説明には次のテーブルを使用します。 :: db.define_table('person', Field('name'), format='%(name)s') Fieldクラスに関する属性 ^^^^^^^^^^^^^^^^^^^^^^^ web2py Book に記載されていた属性を、最初に紹介します。 .. attribute:: Field.type フィールドタイプを保持する属性です。 :: >>> db.person.name.type 'string' .. attribute:: Field.unique ユニーク設定を保持する属性です。 :: >>> db.person.name.unique False .. attribute:: Field.notnull null値を許すかどうかの設定を保持する属性です。 :: >>> db.person.name.notnull False .. attribute:: Field.length フィールド長を保持する属性です。 :: >>> db.person.name.length 512 これらの属性は Fieldコンストラクタにて設定されます。Fieldコンストラクタのパラメータは、属性として参照可能です。 次に web2py Book での記述はなかったですが、代表的な属性を挙げてみます。 .. attribute:: Field.name フィールド名を保持する属性です。 .. attribute:: Field.label フィールドラベルを保持する属性です。 .. attribute:: Field.comment フィールドコメントを保持する属性です。 .. attribute:: Field.default フィールドのデフォルト値を保持する属性です。SQLFORMなどで使用されます。 この他の属性については、詳細はソースを確認するのがよいでしょう。 ソースは web2py\\gluon\\dal.py ファイルの Fieldクラスのコンストラクタ( __init__ )です。 Fieldクラス以外の属性 ^^^^^^^^^^^^^^^^^^^^^ Fieldクラスのコンストラクタでは設定しませんが、Fieldインスタンスに含まれる属性もあります。 web2py Book では次の属性を紹介しています。 .. attribute:: Field._table Tableインスタンスを保持する属性です。 :: >>> type(db.person.name._table) .. attribute:: Field._tablename テーブル名を保持する属性です。 :: >>> db.person.name._tablename 'person' .. attribute:: Field._db DALインスタンスを保持する属性です。 :: >>> type(db.person.name._db) これらの属性は :ref:`class_table` クラスのコンストラクタで設定されています。 参考: `Record Representation `_ | `レコードの表現 `_ ---- .. [#f1] Pythonのinstance型オブジェクトではありませんが、簡単に説明するために **インスタンス** という言葉を使用しています。