Query expressions describe a value or a computation that can be used as part of\nan update, create, filter, order by, annotation, or aggregate. When an\nexpression outputs a boolean value, it may be used directly in filters. There\nare a number of built-in expressions (documented below) that can be used to\nhelp you write queries. Expressions can be combined, or in some cases nested,\nto form more complex computations.
\nDjango supports negation, addition, subtraction, multiplication, division,\nmodulo arithmetic, and the power operator on query expressions, using Python\nconstants, variables, and even other expressions.
\nfrom django.db.models import Count, F, Value\nfrom django.db.models.functions import Length, Upper\n\n# Find companies that have more employees than chairs.\nCompany.objects.filter(num_employees__gt=F('num_chairs'))\n\n# Find companies that have at least twice as many employees\n# as chairs. Both the querysets below are equivalent.\nCompany.objects.filter(num_employees__gt=F('num_chairs') * 2)\nCompany.objects.filter(\n num_employees__gt=F('num_chairs') + F('num_chairs'))\n\n# How many chairs are needed for each company to seat all employees?\n>>> company = Company.objects.filter(\n... num_employees__gt=F('num_chairs')).annotate(\n... chairs_needed=F('num_employees') - F('num_chairs')).first()\n>>> company.num_employees\n120\n>>> company.num_chairs\n50\n>>> company.chairs_needed\n70\n\n# Create a new company using expressions.\n>>> company = Company.objects.create(name='Google', ticker=Upper(Value('goog')))\n# Be sure to refresh it if you need to access the field.\n>>> company.refresh_from_db()\n>>> company.ticker\n'GOOG'\n\n# Annotate models with an aggregated value. Both forms\n# below are equivalent.\nCompany.objects.annotate(num_products=Count('products'))\nCompany.objects.annotate(num_products=Count(F('products')))\n\n# Aggregates can contain complex computations also\nCompany.objects.annotate(num_offerings=Count(F('products') + F('services')))\n\n# Expressions can also be used in order_by(), either directly\nCompany.objects.order_by(Length('name').asc())\nCompany.objects.order_by(Length('name').desc())\n# or using the double underscore lookup syntax.\nfrom django.db.models import CharField\nfrom django.db.models.functions import Length\nCharField.register_lookup(Length)\nCompany.objects.order_by('name__length')\n\n# Boolean expression can be used directly in filters.\nfrom django.db.models import Exists\nCompany.objects.filter(\n Exists(Employee.objects.filter(company=OuterRef('pk'), salary__gt=10))\n)\nF()Link to this heading#An F() object represents the value of a model field, transformed value of a\nmodel field, or annotated column. It makes it possible to refer to model field\nvalues and perform database operations using them without actually having to\npull them out of the database into Python memory.
Instead, Django uses the F() object to generate an SQL expression that\ndescribes the required operation at the database level.
Let's try this with an example. Normally, one might do something like this:
\n# Tintin filed a news story!\nreporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed += 1\nreporter.save()\nHere, we have pulled the value of reporter.stories_filed from the database\ninto memory and manipulated it using familiar Python operators, and then saved\nthe object back to the database. But instead we could also have done:
from django.db.models import F\n\nreporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed = F('stories_filed') + 1\nreporter.save()\nAlthough reporter.stories_filed = F('stories_filed') + 1 looks like a\nnormal Python assignment of value to an instance attribute, in fact it's an SQL\nconstruct describing an operation on the database.
When Django encounters an instance of F(), it overrides the standard Python\noperators to create an encapsulated SQL expression; in this case, one which\ninstructs the database to increment the database field represented by\nreporter.stories_filed.
Whatever value is or was on reporter.stories_filed, Python never gets to\nknow about it - it is dealt with entirely by the database. All Python does,\nthrough Django's F() class, is create the SQL syntax to refer to the field\nand describe the operation.
To access the new value saved this way, the object must be reloaded:
\nreporter = Reporters.objects.get(pk=reporter.pk)\n# Or, more succinctly:\nreporter.refresh_from_db()\nAs well as being used in operations on single instances as above, F() can\nbe used on QuerySets of object instances, with update(). This reduces\nthe two queries we were using above - the get() and the\nsave() - to just one:
reporter = Reporters.objects.filter(name='Tintin')\nreporter.update(stories_filed=F('stories_filed') + 1)\nWe can also use update() to increment\nthe field value on multiple objects - which could be very much faster than\npulling them all into Python from the database, looping over them, incrementing\nthe field value of each one, and saving each one back to the database:
Reporter.objects.all().update(stories_filed=F('stories_filed') + 1)\nF() karena itu menawarkan keuntungan penampilan oleh:
mendapatkan basisdata, daripada Python, untuk melakukan pekerjaan
mengurangi sejumlah permintaan beebrapa tindakan diperlukan
F()Link to this heading#Manfaat berguna lainnya dari F() adalah bahwa memiliki basisdata - daripada Python - memperbaharui sebuah nilai bidang menghindari kondisi balapan.
If two Python threads execute the code in the first example above, one thread\ncould retrieve, increment, and save a field's value after the other has\nretrieved it from the database. The value that the second thread saves will be\nbased on the original value; the work of the first thread will be lost.
\nIf the database is responsible for updating the field, the process is more\nrobust: it will only ever update the field based on the value of the field in\nthe database when the save() or update() is executed, rather\nthan based on its value when the instance was retrieved.
F() diberikan berlanjut setelah Model.save()Link to this heading#F() objects assigned to model fields persist after saving the model\ninstance and will be applied on each save(). For example:
reporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed = F('stories_filed') + 1\nreporter.save()\n\nreporter.name = 'Tintin Jr.'\nreporter.save()\nstories_filed will be updated twice in this case. If it's initially 1,\nthe final value will be 3. This persistence can be avoided by reloading the\nmodel object after saving it, for example, by using\nrefresh_from_db().
F() dalam penyaringanLink to this heading#F() is also very useful in QuerySet filters, where they make it\npossible to filter a set of objects against criteria based on their field\nvalues, rather than on Python values.
Ini didokumentasikan dalam using F() expressions in queries.
\nF() dengan keteranganLink to this heading#F() dapat digunakan untuk membuat bidang-bidang dinamis pada model anda dengan emmadukan bidang-bidang berbeda dengan aritmatik:
company = Company.objects.annotate(\n chairs_needed=F('num_employees') - F('num_chairs'))\nIf the fields that you're combining are of different types you'll need\nto tell Django what kind of field will be returned. Since F() does not\ndirectly support output_field you will need to wrap the expression with\nExpressionWrapper:
from django.db.models import DateTimeField, ExpressionWrapper, F\n\nTicket.objects.annotate(\n expires=ExpressionWrapper(\n F('active_at') + F('duration'), output_field=DateTimeField()))\nKetika mengacukan biadng-bidang terkait seperti ForeignKey, F() mengembalikan nilai primary key daripada instance model:
>> car = Company.objects.annotate(built_by=F('manufacturer'))[0]\n>> car.manufacturer\n<Manufacturer: Toyota>\n>> car.built_by\n3\nF() untuk mengurutkan nilai nullLink to this heading#Use F() and the nulls_first or nulls_last keyword argument to\nExpression.asc() or desc() to control the ordering of\na field's null values. By default, the ordering depends on your database.
For example, to sort companies that haven't been contacted (last_contacted\nis null) after companies that have been contacted:
from django.db.models import F\nCompany.objects.order_by(F('last_contacted').desc(nulls_last=True))\nFunc()Link to this heading#Func() expressions are the base type of all expressions that involve\ndatabase functions like COALESCE and LOWER, or aggregates like SUM.\nThey can be used directly:
from django.db.models import F, Func\n\nqueryset.annotate(field_lower=Func(F('field'), function='LOWER'))\natau mereka dapat digunakan untuk membangun pustaka dari fungsi-fungsi basisdata:
\nclass Lower(Func):\n function = 'LOWER'\n\nqueryset.annotate(field_lower=Lower('field'))\nBut both cases will result in a queryset where each model is annotated with an\nextra attribute field_lower produced, roughly, from the following SQL:
SELECT\n ...\n LOWER("db_table"."field") as "field_lower"\nLihat Fungsi Basisdata untuk daftar fungsi-fungsi basisdata siap-pakai.
\nAPI Func sebagai berikut:
A class attribute describing the function that will be generated.\nSpecifically, the function will be interpolated as the function\nplaceholder within template. Defaults to None.
A class attribute, as a format string, that describes the SQL that is\ngenerated for this function. Defaults to\n'%(function)s(%(expressions)s)'.
If you're constructing SQL like strftime('%W', 'date') and need a\nliteral % character in the query, quadruple it (%%%%) in the\ntemplate attribute because the string is interpolated twice: once\nduring the template interpolation in as_sql() and once in the SQL\ninterpolation with the query parameters in the database cursor.
Sebuah atribut kelas yang menyatakan karakter digunakan utuk menggabungkan daftar dari expressions bersama-sama. Awalan pada ', '.
Sebuah atribut kelas yang menyatakan sejumlah fungsi argumen menerima. Jika atribut ini disetel dan fungsi dipanggil dengan angka berbeda dari pernyataan, TypeError akan dimunculkan. Awalan pada None.
Generates the SQL fragment for the database function. Returns a tuple\n(sql, params), where sql is the SQL string, and params is\nthe list or tuple of query parameters.
Metode as_vendor() harus menggunakan function, template, arg_joiner, dan parameter **extra_context apapun lainnya untuk menyesuaikan SQL sesuai kebutuhan. Sebagai contoh:
django/db/models/functions.pyclass ConcatPair(Func):\n ...\n function = 'CONCAT'\n ...\n\n def as_mysql(self, compiler, connection, **extra_context):\n return super().as_sql(\n compiler, connection,\n function='CONCAT_WS',\n template="%(function)s('', %(expressions)s)",\n **extra_context\n )\nTo avoid an SQL injection vulnerability, extra_context must\nnot contain untrusted user input\nas these values are interpolated into the SQL string rather than passed\nas query parameters, where the database driver would escape them.
The *expressions argument is a list of positional expressions that the\nfunction will be applied to. The expressions will be converted to strings,\njoined together with arg_joiner, and then interpolated into the template\nas the expressions placeholder.
Argumen-argumen penempatan dapat berupa pernyataan atau nilai-nilai Python. String dianggap menjadi acuan kolom dan akan dibungkus dalam pernyataan F() selagi nilai-nilai lain akan dibungkus dalam pernyataan Value().
The **extra kwargs are key=value pairs that can be interpolated\ninto the template attribute. To avoid an SQL injection vulnerability,\nextra must not contain untrusted user input as these values are interpolated\ninto the SQL string rather than passed as query parameters, where the database\ndriver would escape them.
Kata kunci function, template, dan arg_joiner dapat digunakan untuk mengganti atribut-atribut dari nama sama tanpa harus menentukan kelas anda sendiri. output_field dapat digunakan untuk menentukkan jenis kembalian yang diharapkan.
Aggregate()Link to this heading#Sebuah pernyataan pengumpulan adalah kasus khusus dari Func() expression yang menginformasikan permintaan bahwa sebuah klausa GROUP BY diwajibkan. Semua dari aggregate functions, seperti Sum() dan Count(), mewarisi dari Aggregate().
Karena Aggregate adalah pernyataan dan membungkus pernyataan, anda dapat mewakili beberapa perhitungan rumit:
from django.db.models import Count\n\nCompany.objects.annotate(\n managers_required=(Count('num_employees') / 4) + Count('num_managers'))\nAPI Aggregate sebagai berikut:
A class attribute, as a format string, that describes the SQL that is\ngenerated for this aggregate. Defaults to\n'%(function)s(%(distinct)s%(expressions)s)'.
Sebuah atribut kelas menggambarkan fungsi pengumpulan yang akan dibangkitkan. Khususnya, function akan dimasukakn sebagai placeholder function dalam template. Awalan pada None.
Awalan menjadi True sejak kebanyakan fungsi pengumpulan dapat digunakan sebagai sumber pernyataan dalam Window.
A class attribute determining whether or not this aggregate function\nallows passing a distinct keyword argument. If set to False\n(default), TypeError is raised if distinct=True is passed.
The expressions positional arguments can include expressions, transforms of\nthe model field, or the names of model fields. They will be converted to a\nstring and used as the expressions placeholder within the template.
Arfumen output_field membutuhkan contoh sebuah bidang model, seperti IntegerField() atau BooleanField(), menjadi Django akan memuat nilai setelah itu diambil dari basisdata. Biasanya tidak ada argumen dibutuhkan ketika menginstansiasi bidang model sebagai argumen apapun terkait pada pengesahan data (max_length, max_digits, dll.) tidak akan dipaksa pada nilai keluaran pernyataan.
Catat bahwa output_field hanya diwajibkan ketika Django tidak dapat menentukan jenis bidang apa hasil seharusnya. Pernyataan rumit yang mencampurkan jenis-jenis bidang harus menentukan output_field diharapkan. Sebagai contoh, menambahkan sebuah IntegerField() dan sebuah FloatField() bersama-sama harus mungkin memiliki output_field=FloatField() ditentukan.
The distinct argument determines whether or not the aggregate function\nshould be invoked for each distinct value of expressions (or set of\nvalues, for multiple expressions). The argument is only supported on\naggregates that have allow_distinct set to True.
Argumen filter mengambil sebuah Q object yang digunakan untuk menyaring baris yang dikumpulkan. Lihat Pengumpulan bersyarat dan Penyaringan pada keterangan untuk contoh penggunaan.
kwarg **extra adalah pasangan key=value yang dapat ditambahkan kedalam atribut template.
You can create your own aggregate functions, too. At a minimum, you need to\ndefine function, but you can also completely customize the SQL that is\ngenerated. Here's a brief example:
from django.db.models import Aggregate\n\nclass Sum(Aggregate):\n # Supports SUM(ALL field).\n function = 'SUM'\n template = '%(function)s(%(all_values)s%(expressions)s)'\n allow_distinct = False\n\n def __init__(self, expression, all_values=False, **extra):\n super().__init__(\n expression,\n all_values='ALL ' if all_values else '',\n **extra\n )\nValue()Link to this heading#A Value() object represents the smallest possible component of an\nexpression: a simple value. When you need to represent the value of an integer,\nboolean, or string within an expression, you can wrap that value within a\nValue().
You will rarely need to use Value() directly. When you write the expression\nF('field') + 1, Django implicitly wraps the 1 in a Value(),\nallowing simple values to be used in more complex expressions. You will need to\nuse Value() when you want to pass a string to an expression. Most\nexpressions interpret a string argument as the name of a field, like\nLower('name').
The value argument describes the value to be included in the expression,\nsuch as 1, True, or None. Django knows how to convert these Python\nvalues into their corresponding database type.
The output_field argument should be a model field instance, like\nIntegerField() or BooleanField(), into which Django will load the value\nafter it's retrieved from the database. Usually no arguments are needed when\ninstantiating the model field as any arguments relating to data validation\n(max_length, max_digits, etc.) will not be enforced on the expression's\noutput value. If no output_field is specified it will be tentatively\ninferred from the type of the provided value, if possible. For\nexample, passing an instance of datetime.datetime as value\nwould default output_field to DateTimeField.
ExpressionWrapper()Link to this heading#ExpressionWrapper surrounds another expression and provides access to\nproperties, such as output_field, that may not be available on other\nexpressions. ExpressionWrapper is necessary when using arithmetic on\nF() expressions with different types as described in\nMenggunakan F() dengan keterangan.
Conditional expressions allow you to use if ... elif ...\nelse logic in queries. Django natively supports SQL CASE\nexpressions. For more details see Pernyataan Bersyarat.
Subquery()Link to this heading#You can add an explicit subquery to a QuerySet using the Subquery\nexpression.
For example, to annotate each post with the email address of the author of the\nnewest comment on that post:
\n>>> from django.db.models import OuterRef, Subquery\n>>> newest = Comment.objects.filter(post=OuterRef('pk')).order_by('-created_at')\n>>> Post.objects.annotate(newest_commenter_email=Subquery(newest.values('email')[:1]))\nPada PostgreSQL, SQL terlihat seperti:
\nSELECT "post"."id", (\n SELECT U0."email"\n FROM "comment" U0\n WHERE U0."post_id" = ("post"."id")\n ORDER BY U0."created_at" DESC LIMIT 1\n) AS "newest_commenter_email" FROM "post"\nUse OuterRef when a queryset in a Subquery needs to refer to a field\nfrom the outer query or its transform. It acts like an F expression\nexcept that the check to see if it refers to a valid field isn't made until the\nouter queryset is resolved.
Instances of OuterRef may be used in conjunction with nested instances\nof Subquery to refer to a containing queryset that isn't the immediate\nparent. For example, this queryset would need to be within a nested pair of\nSubquery instances to resolve correctly:
>>> Book.objects.filter(author=OuterRef(OuterRef('pk')))\nThere are times when a single column must be returned from a Subquery, for\ninstance, to use a Subquery as the target of an __in lookup. To return\nall comments for posts published within the last day:
>>> from datetime import timedelta\n>>> from django.utils import timezone\n>>> one_day_ago = timezone.now() - timedelta(days=1)\n>>> posts = Post.objects.filter(published_at__gte=one_day_ago)\n>>> Comment.objects.filter(post__in=Subquery(posts.values('pk')))\nIn this case, the subquery must use values()\nto return only a single column: the primary key of the post.
To prevent a subquery from returning multiple rows, a slice ([:1]) of the\nqueryset is used:
>>> subquery = Subquery(newest.values('email')[:1])\n>>> Post.objects.annotate(newest_commenter_email=subquery)\nIn this case, the subquery must only return a single column and a single\nrow: the email address of the most recently created comment.
\n(Using get() instead of a slice would fail because the\nOuterRef cannot be resolved until the queryset is used within a\nSubquery.)
Exists()Link to this heading#Exists is a Subquery subclass that uses an SQL EXISTS statement. In\nmany cases it will perform better than a subquery since the database is able to\nstop evaluation of the subquery when a first matching row is found.
For example, to annotate each post with whether or not it has a comment from\nwithin the last day:
\n>>> from django.db.models import Exists, OuterRef\n>>> from datetime import timedelta\n>>> from django.utils import timezone\n>>> one_day_ago = timezone.now() - timedelta(days=1)\n>>> recent_comments = Comment.objects.filter(\n... post=OuterRef('pk'),\n... created_at__gte=one_day_ago,\n... )\n>>> Post.objects.annotate(recent_comment=Exists(recent_comments))\nPada PostgreSQL, SQL terlihat seperti:
\nSELECT "post"."id", "post"."published_at", EXISTS(\n SELECT (1) as "a"\n FROM "comment" U0\n WHERE (\n U0."created_at" >= YYYY-MM-DD HH:MM:SS AND\n U0."post_id" = "post"."id"\n )\n LIMIT 1\n) AS "recent_comment" FROM "post"\nIt's unnecessary to force Exists to refer to a single column, since the\ncolumns are discarded and a boolean result is returned. Similarly, since\nordering is unimportant within an SQL EXISTS subquery and would only\ndegrade performance, it's automatically removed.
Anda dapat meminta menggunakan NOT EXISTS dengan ~Exists().
Subquery() or Exists() expressionsLink to this heading#Subquery() that returns a boolean value and Exists() may be used as a\ncondition in When expressions, or to\ndirectly filter a queryset:
>>> recent_comments = Comment.objects.filter(...) # From above\n>>> Post.objects.filter(Exists(recent_comments))\nThis will ensure that the subquery will not be added to the SELECT columns,\nwhich may result in a better performance.
Subquery expressionLink to this heading#Aggregates may be used within a Subquery, but they require a specific\ncombination of filter(), values(), and\nannotate() to get the subquery grouping correct.
Assuming both models have a length field, to find posts where the post\nlength is greater than the total length of all combined comments:
>>> from django.db.models import OuterRef, Subquery, Sum\n>>> comments = Comment.objects.filter(post=OuterRef('pk')).order_by().values('post')\n>>> total_comments = comments.annotate(total=Sum('length')).values('total')\n>>> Post.objects.filter(length__gt=Subquery(total_comments))\nThe initial filter(...) limits the subquery to the relevant parameters.\norder_by() removes the default ordering\n(if any) on the Comment model. values('post') aggregates comments by\nPost. Finally, annotate(...) performs the aggregation. The order in\nwhich these queryset methods are applied is important. In this case, since the\nsubquery must be limited to a single column, values('total') is required.
This is the only way to perform an aggregation within a Subquery, as\nusing aggregate() attempts to evaluate the queryset (and if\nthere is an OuterRef, this will not be possible to resolve).
Terkadang pernyataan basisdata tidak dapat dengan mudah menyatakan klausa WHERE rumit. Dalam sisi kasus ini, pernyataan RawSQL. Sebagai contoh:
>>> from django.db.models.expressions import RawSQL\n>>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (param,)))\nThese extra lookups may not be portable to different database engines (because\nyou're explicitly writing SQL code) and violate the DRY principle, so you\nshould avoid them if possible.
\nRawSQL expressions can also be used as the target of __in filters:
>>> queryset.filter(id__in=RawSQL("select id from sometable where col = %s", (param,)))\nWindow functions provide a way to apply functions on partitions. Unlike a\nnormal aggregation function which computes a final result for each set defined\nby the group by, window functions operate on frames and\npartitions, and compute the result for each row.
\nYou can specify multiple windows in the same query which in Django ORM would be\nequivalent to including multiple expressions in a QuerySet.annotate() call. The ORM doesn't make use of named windows,\ninstead they are part of the selected columns.
\nDefaults to False. The SQL standard disallows referencing window\nfunctions in the WHERE clause and Django raises an exception when\nconstructing a QuerySet that would do that.
Defaults to %(expression)s OVER (%(window)s)'. If only the\nexpression argument is provided, the window clause will be blank.
Kelas Windows adalah pernyataan utama untuk klausa OVER.
The expression argument is either a window function, an aggregate function, or\nan expression that's compatible in a window clause.
The partition_by argument accepts an expression or a sequence of\nexpressions (column names should be wrapped in an F-object) that control\nthe partitioning of the rows. Partitioning narrows which rows are used to\ncompute the result set.
output_field ditentukan baik sebagai argumen atau oleh pernyataan.
The order_by argument accepts an expression or a sequence of expressions on\nwhich you can call asc() and\ndesc(). The ordering controls the order in\nwhich the expression is applied. For example, if you sum over the rows in a\npartition, the first result is the value of the first row, the second is the\nsum of first and second row.
Parameter frame menentukan baris lain mana yang harus digunakan dalam perhitungan. Lihat Kerangka untuk rincian.
Sebagai contoh, untuk memberi keterangan setiap film dengan penilaian rerata untuk film berdasarkan studio sama dalam aliran dan tahun terbitan yang sama:
\n>>> from django.db.models import Avg, F, Window\n>>> from django.db.models.functions import ExtractYear\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'),\n>>> partition_by=[F('studio'), F('genre')],\n>>> order_by=ExtractYear('released').asc(),\n>>> ),\n>>> )\nThis allows you to check if a movie is rated better or worse than its peers.
\nYou may want to apply multiple expressions over the same window, i.e., the\nsame partition and frame. For example, you could modify the previous example\nto also include the best and worst rating in each movie's group (same studio,\ngenre, and release year) by using three window functions in the same query. The\npartition and ordering from the previous example is extracted into a dictionary\nto reduce repetition:
\n>>> from django.db.models import Avg, F, Max, Min, Window\n>>> from django.db.models.functions import ExtractYear\n>>> window = {\n>>> 'partition_by': [F('studio'), F('genre')],\n>>> 'order_by': ExtractYear('released').asc(),\n>>> }\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'), **window,\n>>> ),\n>>> best=Window(\n>>> expression=Max('rating'), **window,\n>>> ),\n>>> worst=Window(\n>>> expression=Min('rating'), **window,\n>>> ),\n>>> )\nAmong Django's built-in database backends, MySQL 8.0.2+, PostgreSQL, and Oracle\nsupport window expressions. Support for different window expression features\nvaries among the different databases. For example, the options in\nasc() and\ndesc() may not be supported. Consult the\ndocumentation for your database as needed.
Untuk sebuah kerangka jendela, anda dapat milih salah satu urutan berdasarkan-jangkauan dari baris atau sebuah urutan biasa dari baris.
\nAtribut ini disetel menjadi 'RANGE'.
PostgreSQL mempunyai dukungan terbatas untuk ValueRange dan hanya mendukung menggunakan dari titik standar awal dan akhir, seperti CURRENT ROW dan UNBOUNDED FOLLOWING.
Atribut ini disetel menjadi 'ROWS'.
Kedua kelas mengembalikan SQL dengan cetakan:
\n%(frame_type)s BETWEEN %(start)s AND %(end)s\nFrames narrow the rows that are used for computing the result. They shift from\nsome start point to some specified end point. Frames can be used with and\nwithout partitions, but it's often a good idea to specify an ordering of the\nwindow to ensure a deterministic result. In a frame, a peer in a frame is a row\nwith an equivalent value, or all rows if an ordering clause isn't present.
\nThe default starting point for a frame is UNBOUNDED PRECEDING which is the\nfirst row of the partition. The end point is always explicitly included in the\nSQL generated by the ORM and is by default UNBOUNDED FOLLOWING. The default\nframe includes all rows from the partition to the last row in the set.
The accepted values for the start and end arguments are None, an\ninteger, or zero. A negative integer for start results in N preceding,\nwhile None yields UNBOUNDED PRECEDING. For both start and end,\nzero will return CURRENT ROW. Positive integers are accepted for end.
There's a difference in what CURRENT ROW includes. When specified in\nROWS mode, the frame starts or ends with the current row. When specified in\nRANGE mode, the frame starts or ends at the first or last peer according to\nthe ordering clause. Thus, RANGE CURRENT ROW evaluates the expression for\nrows which have the same value specified by the ordering. Because the template\nincludes both the start and end points, this may be expressed with:
ValueRange(start=0, end=0)\nIf a movie's "peers" are described as movies released by the same studio in the\nsame genre in the same year, this RowRange example annotates each movie\nwith the average rating of a movie's two prior and two following peers:
>>> from django.db.models import Avg, F, RowRange, Window\n>>> from django.db.models.functions import ExtractYear\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'),\n>>> partition_by=[F('studio'), F('genre')],\n>>> order_by=ExtractYear('released').asc(),\n>>> frame=RowRange(start=-2, end=2),\n>>> ),\n>>> )\nIf the database supports it, you can specify the start and end points based on\nvalues of an expression in the partition. If the released field of the\nMovie model stores the release month of each movies, this ValueRange\nexample annotates each movie with the average rating of a movie's peers\nreleased between twelve months before and twelve months after the each movie.
>>> from django.db.models import Avg, F, ValueRange, Window\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'),\n>>> partition_by=[F('studio'), F('genre')],\n>>> order_by=F('released').asc(),\n>>> frame=ValueRange(start=-12, end=12),\n>>> ),\n>>> )\nBelow you'll find technical implementation details that may be useful to\nlibrary authors. The technical API and examples below will help with\ncreating generic query expressions that can extend the built-in functionality\nthat Django provides.
\nQuery expressions implement the query expression API,\nbut also expose a number of extra methods and attributes listed below. All\nquery expressions must inherit from Expression() or a relevant\nsubclass.
Ketika pernyataan permintaan membungkus pernyataan lain, itu adalah tanggung jawab untuk memanggil metode-metode sesuai pada pernyataan dibungkus.
\nBeritahu Django bahwa pernyataan ini mengandung sebuah pengumpulan dan bahwa sebuah klausa GROUP BY butuh ditambahkan ke permintaan.
Beritahu Django bahwa pernyataan ini mengandung pernyataan Window. Itu digunakan, sebagai contoh, melarang pernyataan fungsi-fungsi jendela dalam permintaan yang merubah data.
Memberitahu Django bahwa pernyataan ini dapat diacukan dalam QuerySet.filter(). Awalan ke True.
Beritahu Django bahwa pernyataan ini dapat digunakan sebagai pernyataan sumber dalam Window. Awalan menjadi False.
Provides the chance to do any pre-processing or validation of\nthe expression before it's added to the query. resolve_expression()\nmust also be called on any nested expressions. A copy() of self\nshould be returned with any necessary transformations.
query adalah backend penerapan query.
allow_joins adalah boolean yang mengizinkan atau menolak penggunaan join dalam permintaan.
reuse adalah kumpula dari penggunaan kembali join untuk skenario multi-join.
summarize adalah boolean yang, ketika True, sinyal-sinyal yang meminta sedang dihitung adalah permintaan keseluruhan terminal.
for_save is a boolean that, when True, signals that the query\nbeing executed is performing a create or update.
Mengembalikan daftar terurut dari pernyataan paling dalam. Sebagai contoh:
\n>>> Sum(F('foo')).get_source_expressions()\n[F('foo')]\nMengambil daftar dari pernyataan dan menyimpan mereka seperti itu get_source_expressions() dapat mengembalikan mereka.
Returns a clone (copy) of self, with any column aliases relabeled.\nColumn aliases are renamed when subqueries are created.\nrelabeled_clone() should also be called on any nested expressions\nand assigned to the clone.
"change_map" adalah sebuah dictionary memetakan nama lain lama ke nama lain baru.
\nContoh:
\ndef relabeled_clone(self, change_map):\n clone = copy.copy(self)\n clone.expression = self.expression.relabeled_clone(change_map)\n return clone\nSebuah kaitan mengizinkan pernyataan untuk memaksa value menjadi lebih jenis yang sesuai.
expression is the same as self.
Responsible for returning the list of columns references by\nthis expression. get_group_by_cols() should be called on any\nnested expressions. F() objects, in particular, hold a reference\nto a column. The alias parameter will be None unless the\nexpression has been annotated and is used for grouping.
Mengembalikan pernyataan siap untuk diurutkan dalam urutan menaik.
\nnulls_first dan nulls_last menentukan bagaimana nilai-nilai null diurutkan. Lihat Menggunakan F() untuk mengurutkan nilai null untuk contoh penggunaan.
Mengembalikan pernyataan siap untuk diurutkan dalam urutan menurun.
\nnulls_first dan nulls_last menentukan bagaimana nilai-nilai null diurutkan. Lihat Menggunakan F() untuk mengurutkan nilai null untuk contoh penggunaan.
Mengembalikan selft dengan perubahan apapun diwajibkan untuk mengembalikan pilihan pengurutan dalam sebuah panggilan order_by. Sebagai sebuah contoh, sebuah pernyataan menerapkan NULLS LAST akan merubah nilainya menjadi NULLS FIRST. Perubahan-perubahan hanya diwajibkan untuk pernyataan yang menerapkan pilihat pengurutan seperti OrderBy. Metode ini dipanggil ketika reverse() pada sebuah kumpulan permintaan.
You can write your own query expression classes that use, and can integrate\nwith, other query expressions. Let's step through an example by writing an\nimplementation of the COALESCE SQL function, without using the built-in\nFunc() expressions.
Fungsi SQL COALESCE ditentukan sebagai mengambil daftar kolom atau nilai. Itu akan mengembalikan kolom pertama atau nilai yang bukan NULL.
Kami akan memulai dengan menentukan cetakan untuk digunakan pembangkitan SQL dan sebuah metode __init__() untuk mensetel beberapa atribut:
import copy\nfrom django.db.models import Expression\n\nclass Coalesce(Expression):\n template = 'COALESCE( %(expressions)s )'\n\n def __init__(self, expressions, output_field):\n super().__init__(output_field=output_field)\n if len(expressions) < 2:\n raise ValueError('expressions must have at least 2 elements')\n for expression in expressions:\n if not hasattr(expression, 'resolve_expression'):\n raise TypeError('%r is not an Expression' % expression)\n self.expressions = expressions\nWe do some basic validation on the parameters, including requiring at least\n2 columns or values, and ensuring they are expressions. We are requiring\noutput_field here so that Django knows what kind of model field to assign\nthe eventual result to.
Now we implement the pre-processing and validation. Since we do not have\nany of our own validation at this point, we delegate to the nested\nexpressions:
\ndef resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False):\n c = self.copy()\n c.is_summary = summarize\n for pos, expression in enumerate(self.expressions):\n c.expressions[pos] = expression.resolve_expression(query, allow_joins, reuse, summarize, for_save)\n return c\nSelanjutnya, kami menulis metode yang bertanggungjawab untuk membangkitkan SQL:
\ndef as_sql(self, compiler, connection, template=None):\n sql_expressions, sql_params = [], []\n for expression in self.expressions:\n sql, params = compiler.compile(expression)\n sql_expressions.append(sql)\n sql_params.extend(params)\n template = template or self.template\n data = {'expressions': ','.join(sql_expressions)}\n return template % data, sql_params\n\ndef as_oracle(self, compiler, connection):\n """\n Example of vendor specific handling (Oracle in this case).\n Let's make the function name lowercase.\n """\n return self.as_sql(compiler, connection, template='coalesce( %(expressions)s )')\nas_sql() methods can support custom keyword arguments, allowing\nas_vendorname() methods to override data used to generate the SQL string.\nUsing as_sql() keyword arguments for customization is preferable to\nmutating self within as_vendorname() methods as the latter can lead to\nerrors when running on different database backends. If your class relies on\nclass attributes to define data, consider allowing overrides in your\nas_sql() method.
We generate the SQL for each of the expressions by using the\ncompiler.compile() method, and join the result together with commas.\nThen the template is filled out with our data and the SQL and parameters\nare returned.
We've also defined a custom implementation that is specific to the Oracle\nbackend. The as_oracle() function will be called instead of as_sql()\nif the Oracle backend is in use.
Akhirnya, kami menerapkan sisa dari metode yang mengizinkan pernyataan permintaan kami bermain bagus dengan pernyataan permintaan lain:
\ndef get_source_expressions(self):\n return self.expressions\n\ndef set_source_expressions(self, expressions):\n self.expressions = expressions\nMari kita lihat bagaimana itu bekerja:
\n>>> from django.db.models import F, Value, CharField\n>>> qs = Company.objects.annotate(\n... tagline=Coalesce([\n... F('motto'),\n... F('ticker_name'),\n... F('description'),\n... Value('No Tagline')\n... ], output_field=CharField()))\n>>> for c in qs:\n... print("%s: %s" % (c.name, c.tagline))\n...\nGoogle: Do No Evil\nApple: AAPL\nYahoo: Internet Company\nDjango Software Foundation: No Tagline\nSince a Func's keyword arguments for __init__() (**extra) and\nas_sql() (**extra_context) are interpolated into the SQL string rather\nthan passed as query parameters (where the database driver would escape them),\nthey must not contain untrusted user input.
Sebagai contoh, jika substring adalah disediakan-pengguna, fungsi ini rentan pada penyuntikan SQL:
from django.db.models import Func\n\nclass Position(Func):\n function = 'POSITION'\n template = "%(function)s('%(substring)s' in %(expressions)s)"\n\n def __init__(self, expression, substring):\n # substring=substring is an SQL injection vulnerability!\n super().__init__(expression, substring=substring)\nThis function generates an SQL string without any parameters. Since\nsubstring is passed to super().__init__() as a keyword argument, it's\ninterpolated into the SQL string before the query is sent to the database.
Ini adalah tulisan kembali yang sudah diperiksa:
\nclass Position(Func):\n function = 'POSITION'\n arg_joiner = ' IN '\n\n def __init__(self, expression, substring):\n super().__init__(substring, expression)\nDengan substring bukannya dilewatkan sebagai argumen penempatan, itu akan dilewatkan sebagai parameter dalam permintaan basisdata.
Jika anda sedang menggunakan backend basisdata yang menggunakan sintaksis SQL berbeda untuk fungsi tertentu, anda dapat menambah dukungan untuk itu dengan menambal metode baru kedalam kelas fungsi.
\nMari kita katakan kami sedang menulis sebuah backend untuk SQL Server Microsoft yang menggunakan SQL LEN daripada LENGTH untuk fungsi Length. Kami akan membuat penambalan sebuah metode baru disebut as_sqlserver() ke dalam kelas Length:
from django.db.models.functions import Length\n\ndef sqlserver_length(self, compiler, connection):\n return self.as_sql(compiler, connection, function='LEN')\n\nLength.as_sqlserver = sqlserver_length\nAnda dapat menyesuaikan SQL menggunakan parameter template dari as_sql().
Kami menggunakan as_sqlserver() karena django.db.connection.vendor mengembalikan sqlserver untuk backend.
Backend pihak-ketiga dapat mendaftarkan fungsi0fungsi mereka dalam berkas __init__.py tingkat atas dari paket backend atau dalam berkas expressions.py (atau paket) tingkat atas yang diimpor dari __init__.py tngkat atas.
Untuk pengguna proyek yang berharap menambal backend yang mereka gunakan, kode ini harus berada dalam sebuah metode AppConfig.ready().