.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "GDAL-VECTOR-SQL" "1" "Aug 18, 2026" "" "GDAL" .SH "نام (NAME)" gdal-vector-sql \- اعمال دستور(ات) SQL بر روی یک مجموعه داده .sp افزوده شده در نسخه 3.11. .SH "خلاصه دستور (SYNOPSIS)" .INDENT 0.0 .INDENT 3.5 .sp .EX Usage: gdal vector sql [OPTIONS] [] Apply SQL statement(s) to a dataset. Positional arguments: \-i, \-\-dataset, \-\-input Input vector datasets [required] [not available in pipelines] \-o, \-\-output Output vector dataset [not available in pipelines] Common Options: \-h, \-\-help Display help message and exit \-\-json\-usage Display usage as JSON document and exit \-\-config = Configuration option [may be repeated] \-q, \-\-quiet Quiet mode (no progress bar or warning message) [not available in pipelines] Options: \-f, \-\-of, \-\-format, \-\-output\-format Output format (\(dqGDALG\(dq allowed) [not available in pipelines] \-\-co, \-\-creation\-option = Creation option [may be repeated] [not available in pipelines] \-\-lco, \-\-layer\-creation\-option = Layer creation option [may be repeated] [not available in pipelines] \-\-overwrite Whether overwriting existing output dataset is allowed [not available in pipelines] \-\-update Whether to open existing dataset in update mode [not available in pipelines] \-\-overwrite\-layer Whether overwriting existing output layer is allowed [not available in pipelines] \-\-append Whether appending to existing layer is allowed [not available in pipelines] Mutually exclusive with \-\-upsert \-\-skip\-errors Skip errors when writing features [not available in pipelines] \-\-sql |@ SQL statement(s) [may be repeated] [required] \-\-output\-layer Output layer name(s) [may be repeated] \-\-dialect SQL dialect (e.g. OGRSQL, SQLITE) Advanced Options: \-\-if, \-\-input\-format Input formats [may be repeated] [not available in pipelines] \-\-oo, \-\-open\-option = Open options [may be repeated] [not available in pipelines] \-\-output\-oo, \-\-output\-open\-option = Output open options [may be repeated] [not available in pipelines] \-\-upsert Upsert features (implies \(aqappend\(aq) [not available in pipelines] Mutually exclusive with \-\-append .EE .UNINDENT .UNINDENT .SH "توضیحات (DESCRIPTION)" .sp دستور \fBgdal vector sql\fP یک یا چند لایه ارزیابی‌شده از دستورات SQL را بازمی‌گرداند. .sp از نسخه GDAL 3.12 به بعد، هنگام استفاده از \fI\%\-\-update\fP، و بدون مشخص کردن یک مجموعه داده خروجی، این دستور می‌تواند برای اجرای دستوراتی که مجموعه داده ورودی را تغییر می‌دهند، مانند UPDATE، DELETE و غیره به کار رود. .SH "خروجی GDALG (مجموعه داده درجا / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET))" .sp این برنامه از سریال‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از قالب خروجی \fBGDALG\fP پشتیبانی می‌کند. فایل حاصل را می‌توان سپس به عنوان یک مجموعه داده برداری با استفاده از درایور \fI\%GDALG: GDAL Streamed Algorithm\fP باز کرد، و خط لوله مشخص‌شده را به صورت درجا / جریانی (on\-the\-fly / streamed) اعمال نمود. .SH "گزینه‌های اختصاصی برنامه (PROGRAM-SPECIFIC OPTIONS)" .INDENT 0.0 .TP .B \-\-output\-layer نام(های) لایه SQL خروجی. در صورت مشخص نشدن، یک نام لایه عمومی مانند \(dqSELECT\(dq ممکن است ایجاد شود. .sp باید به تعداد دستورات SQL مشخص شود؛ چه به صورت چندین آرگومان \-\-output\-layer، و چه به صورت یک آرگومان واحد که در آن نام لایه‌ها با کاما از یکدیگر جدا شده‌اند. .UNINDENT .INDENT 0.0 .TP .B \-\-quiet افزوده شده در نسخه 3.12. .sp بی‌صدا کردن پیام‌های اطلاعاتی احتمالی. .UNINDENT .INDENT 0.0 .TP .B \-\-sql |@ دستور SQL برای اجرا که یک جدول/لایه را بازمی‌گرداند (معمولاً یک دستور SELECT). .sp می‌تواند برای ایجاد چندین لایه خروجی تکرار شود (تکرار \-\-sql به ازای هر لایه خروجی). .UNINDENT .INDENT 0.0 .TP .B \-\-dialect گویش SQL. .sp به طور پیش‌فرض هنگام استفاده از \fBgdal vector sql\fP\&، گویش بومی SQL یک RDBMS استفاده می‌شود. در صورت استفاده از \fBsql\fP به عنوان مرحله‌ای از \fBgdal vector pipeline\fP، این موضوع تنها زمانی برقرار است که مرحله قبل از \fBsql\fP دستور \fBread\fP باشد، در غیر این صورت از گویش \fI\%OGRSQL\fP استفاده می‌شود. .sp اگر یک منبع داده به صورت بومی از SQL پشتیبانی نکند، حالت پیش‌فرض استفاده از گویش \fBOGRSQL\fP است، که می‌تواند با هر منبع داده‌ای نیز مشخص شود. .sp گویش \fI\%SQL SQLite dialect\fP را می‌توان با مقادیر گویش \fBSQLITE\fP و \fBINDIRECT_SQLITE\fP انتخاب کرد، و می‌توان از آن با هر منبع داده‌ای استفاده نمود. جایگزین کردن گویش پیش‌فرض ممکن است سودمند باشد زیرا قابلیت‌های گویش‌های مختلف SQL با یکدیگر تفاوت دارند. .sp گویش‌های پشتیبانی‌شده را می‌توان با \fBgdal \-\-format\fP بررسی کرد. برای مثال: .INDENT 7.0 .INDENT 3.5 .sp .EX $ gdal \-\-format \(dqPostgreSQL\(dq [...] Supported SQL dialects: NATIVE OGRSQL SQLITE [...] $ gdal \-\-format \(dqESRI Shapefile\(dq [...] Supported SQL dialects: OGRSQL SQLITE [...] .EE .UNINDENT .UNINDENT .UNINDENT.SH "گزینه‌های استاندارد (STANDARD OPTIONS)" .INDENT 0.0 .TP .B \-\-append آیا الحاق عوارض به لایه(های) موجود مجاز است یا خیر. این گزینه در صورت عدم وجود مجموعه داده خروجی، آن را نیز ایجاد می‌کند. .UNINDENT .INDENT 0.0 .TP .B \-\-co, \-\-creation\-option = بسیاری از فرمت‌ها یک یا چند گزینه اختیاری ساخت مجموعه داده دارند که می‌توان از آن‌ها برای کنترل جزئیات فایل ایجادشده استفاده کرد. برای نمونه، درایور GeoPackage از گزینه‌های ساختی برای کنترل نسخه پشتیبانی می‌کند. .sp می‌تواند تکرار شود. .sp گزینه‌های ساخت مجموعه داده در دسترس، بسته به درایور فرمت متفاوت هستند و برخی فرمت‌های ساده اصلاً هیچ گزینه ساختی ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک فرمت را می‌توان با گزینه خط فرمان \fI\%\-\-formats\fP مشاهده کرد، اما مستندات مربوط به همان فرمت منبع موثق اطلاعات درباره گزینه‌های ساخت درایور است. برای مشاهده گزینه‌های ساخت مجاز برای هر فرمت، به مستندات اختصاصی فرمت در \fI\%Vector drivers\fP مراجعه کنید. .sp توجه داشته باشید که گزینه‌های ساخت مجموعه داده با گزینه‌های ساخت لایه متفاوت هستند. .UNINDENT .INDENT 0.0 .TP .B \-\-if, \-\-input\-format نام فرمت/درایوری که باید برای باز کردن فایل(های) ورودی امتحان شود. عموماً نیازی به مشخص کردن آن نیست، اما در مواردی که تشخیص خودکار درایور در انتخاب درایور مناسب ناموفق است، می‌توان از آن برای نادیده گرفتن تشخیص خودکار استفاده کرد. این گزینه می‌تواند چندین بار برای مشخص کردن چند درایور کاندید تکرار شود. توجه داشته باشید که این گزینه درایورهای مذکور را مجبور به باز کردن مجموعه داده نمی‌کند. به‌ویژه، برخی درایورها نیازمندی‌هایی برای پسوند فایل دارند. .sp می‌تواند تکرار شود. .UNINDENT .INDENT 0.0 .TP .B \-\-lco, \-\-layer\-creation\-option = بسیاری از فرمت‌ها یک یا چند گزینه اختیاری ساخت لایه دارند که می‌توان از آن‌ها برای کنترل جزئیات لایه ایجادشده استفاده کرد. برای نمونه، درایور GeoPackage از گزینه‌های ساخت لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا توضیحات و غیره پشتیبانی می‌کند. .sp می‌تواند تکرار شود. .sp گزینه‌های ساخت لایه در دسترس، بسته به درایور فرمت متفاوت هستند و برخی فرمت‌های ساده اصلاً هیچ گزینه ساخت لایه‌ای ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک فرمت را می‌توان با گزینه خط فرمان \fI\%\-\-formats\fP مشاهده کرد، اما مستندات مربوط به همان فرمت منبع موثق اطلاعات درباره گزینه‌های ساخت درایور است. برای مشاهده گزینه‌های ساخت مجاز برای هر فرمت، به مستندات اختصاصی فرمت در \fI\%Vector drivers\fP مراجعه کنید. .sp توجه داشته باشید که گزینه‌های ساخت لایه با گزینه‌های ساخت مجموعه داده متفاوت هستند. .UNINDENT .INDENT 0.0 .TP .B \-\-oo, \-\-open\-option = گزینه باز کردن مجموعه داده (مختص هر فرمت). .sp می‌تواند تکرار شود. .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-of, \-\-format, \-\-output\-format فرمت برداری خروجی مورد استفاده. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: \fBgdal \-\-formats | grep vector | grep rw | sort\fP .UNINDENT .INDENT 0.0 .TP .B \-\-output\-open\-option, \-\-output\-oo = در نسخه 3.12 اضافه شد. .sp گزینه باز کردن مجموعه داده برای مجموعه داده خروجی (مختص هر فرمت). .sp می‌تواند تکرار شود. .UNINDENT .INDENT 0.0 .TP .B \-\-overwrite به برنامه اجازه می‌دهد فایل یا مجموعه داده مقصد موجود را بازنویسی کند. در غیر این صورت، به‌طور پیش‌فرض، اگر فایل یا مجموعه داده مقصد از قبل وجود داشته باشد، \fBgdal\fP با خطا متوقف می‌شود. .UNINDENT .INDENT 0.0 .TP .B \-\-overwrite\-layer آیا بازنویسی لایه برداری خروجیِ موجود مجاز است یا خیر. .UNINDENT .INDENT 0.0 .TP .B \-\-skip\-errors در نسخه 3.12 اضافه شد. .sp آیا خطاهای مربوط به نوشتن عارضه(ها) باید نادیده گرفته شوند یا خیر. توجه داشته باشید که این گزینه اندازه واحد تراکنش را بر روی یک عارضه در هر نوبت تنظیم می‌کند که ممکن است هنگام درج در پایگاه‌های داده باعث افت شدید سرعت شود. .UNINDENT .INDENT 0.0 .TP .B \-\-update آیا مجموعه داده خروجی موجود در حالت به‌روزرسانی باز شود یا خیر. .UNINDENT .INDENT 0.0 .TP .B \-\-upsert در نسخه 3.12 اضافه شد. .sp گونه‌ای از \fI\%\-\-append\fP که در آن به جای الحاق با \fI\%OGRLayer::CreateFeature()\fP\&، از عملیات \fI\%OGRLayer::UpsertFeature()\fP برای درج یا به‌روزرسانی عوارض استفاده می‌شود. .sp این قابلیت در حال حاضر تنها در چند درایور پیاده‌سازی شده است: \fI\%GPKG \-\- GeoPackage vector\fP، \fI\%Elasticsearch: Geographically Encoded Objects for Elasticsearch\fP و \fI\%MongoDBv3\fP (درایورهایی که upsert را پیاده‌سازی کرده‌اند، قابلیت \fI\%GDAL_DCAP_UPSERT\fP را ارائه می‌دهند). .sp عملیات upsert در صورت مقداردهی شدن FID عارضه ورودی (و خالی نبودن نام ستون FID)، از آن به عنوان کلید برای به‌روزرسانی عوارض موجود استفاده می‌کند. بسیار حیاتی است که اطمینان حاصل شود FID در لایه‌های مبدأ و مقصد با یکدیگر سازگار هستند. .sp برای درایور GPKG، در صورتی که یک ستون UNIQUE وجود داشته باشد که کلید اصلی عدد صحیح (integer primary key) نباشد، انجام upsert برای عوارضی که FID آن‌ها تنظیم نشده یا بی‌اهمیت (non\-significant) است نیز امکان‌پذیر است (از گزینه \fB\-\-unset\-fid\fP در دستور \fI\%gdal vector edit\fP می‌توان برای نادیده گرفتن FID عارضه مبدأ استفاده کرد). .UNINDENT .INDENT 0.0 .TP .B \-q, \-\-quiet غیرفعال کردن نوار پیشرفت و برخی پیام‌های هشدار. .UNINDENT.SH "کد وضعیت بازگشتی (RETURN STATUS CODE)" .sp برنامه در صورت موفقیت کد وضعیت ۰ و در صورت بروز خطا مقداری غیر صفر بازمی‌گرداند (خطاهای غیرمسدودکننده که به صورت هشدار صادر می‌شوند، اجرای موفقیت‌آمیز در نظر گرفته می‌شوند). .SH "مثال‌ها (EXAMPLES)" .SS مثال ۱: تولید یک فایل GeoPackage با لایه‌ای مرتب‌شده بر اساس جمعیت نزولی .INDENT 0.0 .INDENT 3.5 .sp .EX $ gdal vector sql in.gpkg out.gpkg \-\-output\-layer country_sorted_by_pop \-\-sql=\(dqSELECT * FROM country ORDER BY pop DESC\(dq .EE .UNINDENT .UNINDENT .SS مثال ۲: تولید یک فایل GeoPackage با ۲ لایه نتیجه‌ی SQL .INDENT 0.0 .INDENT 3.5 .sp .EX $ gdal vector sql in.gpkg out.gpkg \-\-output\-layer=beginning,end \-\-sql=\(dqSELECT * FROM my_layer LIMIT 100\(dq \-\-sql=\(dqSELECT * FROM my_layer OFFSET 100000 LIMIT 100\(dq .EE .UNINDENT .UNINDENT .SS مثال ۳: تغییر در‌جای (in\-place) یک مجموعه‌داده GeoPackage .INDENT 0.0 .INDENT 3.5 .sp .EX $ gdal vector sql \-\-update my.gpkg \-\-sql \(dqDELETE FROM countries WHERE pop > 1e6\(dq .EE .UNINDENT .UNINDENT .SS مثال ۴: افزودن یک فیلد جدید به لایه موجود یک GeoPackage .INDENT 0.0 .INDENT 3.5 .sp .EX $ gdal vector sql \-\-update my.gpkg \-\-sql \(dqALTER TABLE countries ADD COLUMN abbrev STRING(10)\(dq .EE .UNINDENT .UNINDENT .SS مثال ۵: الحاق به یک لایه موجود در یک فایل GeoPackage .INDENT 0.0 .INDENT 3.5 .sp .EX $ gdal vector pipeline read europe.gpkg ! \e sql \-\-sql \(dqSELECT * FROM country WHERE pop > 1e6\(dq ! \e write \-\-append \-\-output\-layer\-name=world world.gpkg .EE .UNINDENT .UNINDENT .SH "نویسندگان (AUTHORS)" Even Rouault .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 1998-2026 .\" Generated by docutils manpage writer. .