GDAL-VECTOR-SQL(1) GDAL GDAL-VECTOR-SQL(1)

gdal-vector-sql - اعمال دستور(ات) SQL بر روی یک مجموعه داده

افزوده شده در نسخه 3.11.

Usage: gdal vector sql [OPTIONS] <INPUT> [<OUTPUT>]
Apply SQL statement(s) to a dataset.
Positional arguments:
  -i, --dataset, --input <INPUT>                       Input vector datasets [required] [not available in pipelines]
  -o, --output <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 <KEY>=<VALUE>                               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>  Output format ("GDALG" allowed) [not available in pipelines]
  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
  --lco, --layer-creation-option <KEY>=<VALUE>         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 <statement>|@<filename>                        SQL statement(s) [may be repeated] [required]
  --output-layer <OUTPUT-LAYER>                        Output layer name(s) [may be repeated]
  --dialect <DIALECT>                                  SQL dialect (e.g. OGRSQL, SQLITE)
Advanced Options:
  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated] [not available in pipelines]
  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated] [not available in pipelines]
  --output-oo, --output-open-option <KEY>=<VALUE>      Output open options [may be repeated] [not available in pipelines]
  --upsert                                             Upsert features (implies 'append') [not available in pipelines]
                                                       Mutually exclusive with --append

دستور gdal vector sql یک یا چند لایه ارزیابی‌شده از دستورات SQL را بازمی‌گرداند.

از نسخه GDAL 3.12 به بعد، هنگام استفاده از --update، و بدون مشخص کردن یک مجموعه داده خروجی، این دستور می‌تواند برای اجرای دستوراتی که مجموعه داده ورودی را تغییر می‌دهند، مانند UPDATE، DELETE و غیره به کار رود.

این برنامه از سریال‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از قالب خروجی GDALG پشتیبانی می‌کند. فایل حاصل را می‌توان سپس به عنوان یک مجموعه داده برداری با استفاده از درایور GDALG: GDAL Streamed Algorithm باز کرد، و خط لوله مشخص‌شده را به صورت درجا / جریانی (on-the-fly / streamed) اعمال نمود.

نام(های) لایه SQL خروجی. در صورت مشخص نشدن، یک نام لایه عمومی مانند "SELECT" ممکن است ایجاد شود.

باید به تعداد دستورات SQL مشخص شود؛ چه به صورت چندین آرگومان --output-layer، و چه به صورت یک آرگومان واحد که در آن نام لایه‌ها با کاما از یکدیگر جدا شده‌اند.

افزوده شده در نسخه 3.12.

بی‌صدا کردن پیام‌های اطلاعاتی احتمالی.

دستور SQL برای اجرا که یک جدول/لایه را بازمی‌گرداند (معمولاً یک دستور SELECT).

می‌تواند برای ایجاد چندین لایه خروجی تکرار شود (تکرار --sql <value> به ازای هر لایه خروجی).

گویش SQL.

به طور پیش‌فرض هنگام استفاده از gdal vector sql، گویش بومی SQL یک RDBMS استفاده می‌شود. در صورت استفاده از sql به عنوان مرحله‌ای از gdal vector pipeline، این موضوع تنها زمانی برقرار است که مرحله قبل از sql دستور read باشد، در غیر این صورت از گویش OGRSQL استفاده می‌شود.

اگر یک منبع داده به صورت بومی از SQL پشتیبانی نکند، حالت پیش‌فرض استفاده از گویش OGRSQL است، که می‌تواند با هر منبع داده‌ای نیز مشخص شود.

گویش SQL SQLite dialect را می‌توان با مقادیر گویش SQLITE و INDIRECT_SQLITE انتخاب کرد، و می‌توان از آن با هر منبع داده‌ای استفاده نمود. جایگزین کردن گویش پیش‌فرض ممکن است سودمند باشد زیرا قابلیت‌های گویش‌های مختلف SQL با یکدیگر تفاوت دارند.

گویش‌های پشتیبانی‌شده را می‌توان با gdal --format بررسی کرد. برای مثال:

$ gdal --format "PostgreSQL"
[...]
Supported SQL dialects: NATIVE OGRSQL SQLITE
[...]
$ gdal --format "ESRI Shapefile"
[...]
Supported SQL dialects: OGRSQL SQLITE
[...]
آیا الحاق عوارض به لایه(های) موجود مجاز است یا خیر. این گزینه در صورت عدم وجود مجموعه داده خروجی، آن را نیز ایجاد می‌کند.
بسیاری از فرمت‌ها یک یا چند گزینه اختیاری ساخت مجموعه داده دارند که می‌توان از آن‌ها برای کنترل جزئیات فایل ایجادشده استفاده کرد. برای نمونه، درایور GeoPackage از گزینه‌های ساختی برای کنترل نسخه پشتیبانی می‌کند.

می‌تواند تکرار شود.

گزینه‌های ساخت مجموعه داده در دسترس، بسته به درایور فرمت متفاوت هستند و برخی فرمت‌های ساده اصلاً هیچ گزینه ساختی ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک فرمت را می‌توان با گزینه خط فرمان --formats مشاهده کرد، اما مستندات مربوط به همان فرمت منبع موثق اطلاعات درباره گزینه‌های ساخت درایور است. برای مشاهده گزینه‌های ساخت مجاز برای هر فرمت، به مستندات اختصاصی فرمت در Vector drivers مراجعه کنید.

توجه داشته باشید که گزینه‌های ساخت مجموعه داده با گزینه‌های ساخت لایه متفاوت هستند.

نام فرمت/درایوری که باید برای باز کردن فایل(های) ورودی امتحان شود. عموماً نیازی به مشخص کردن آن نیست، اما در مواردی که تشخیص خودکار درایور در انتخاب درایور مناسب ناموفق است، می‌توان از آن برای نادیده گرفتن تشخیص خودکار استفاده کرد. این گزینه می‌تواند چندین بار برای مشخص کردن چند درایور کاندید تکرار شود. توجه داشته باشید که این گزینه درایورهای مذکور را مجبور به باز کردن مجموعه داده نمی‌کند. به‌ویژه، برخی درایورها نیازمندی‌هایی برای پسوند فایل دارند.

می‌تواند تکرار شود.

بسیاری از فرمت‌ها یک یا چند گزینه اختیاری ساخت لایه دارند که می‌توان از آن‌ها برای کنترل جزئیات لایه ایجادشده استفاده کرد. برای نمونه، درایور GeoPackage از گزینه‌های ساخت لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا توضیحات و غیره پشتیبانی می‌کند.

می‌تواند تکرار شود.

گزینه‌های ساخت لایه در دسترس، بسته به درایور فرمت متفاوت هستند و برخی فرمت‌های ساده اصلاً هیچ گزینه ساخت لایه‌ای ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک فرمت را می‌توان با گزینه خط فرمان --formats مشاهده کرد، اما مستندات مربوط به همان فرمت منبع موثق اطلاعات درباره گزینه‌های ساخت درایور است. برای مشاهده گزینه‌های ساخت مجاز برای هر فرمت، به مستندات اختصاصی فرمت در Vector drivers مراجعه کنید.

توجه داشته باشید که گزینه‌های ساخت لایه با گزینه‌های ساخت مجموعه داده متفاوت هستند.

گزینه باز کردن مجموعه داده (مختص هر فرمت).

می‌تواند تکرار شود.

فرمت برداری خروجی مورد استفاده. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: gdal --formats | grep vector | grep rw | sort
در نسخه 3.12 اضافه شد.

گزینه باز کردن مجموعه داده برای مجموعه داده خروجی (مختص هر فرمت).

می‌تواند تکرار شود.

به برنامه اجازه می‌دهد فایل یا مجموعه داده مقصد موجود را بازنویسی کند. در غیر این صورت، به‌طور پیش‌فرض، اگر فایل یا مجموعه داده مقصد از قبل وجود داشته باشد، gdal با خطا متوقف می‌شود.
--overwrite-layer
آیا بازنویسی لایه برداری خروجیِ موجود مجاز است یا خیر.
در نسخه 3.12 اضافه شد.

آیا خطاهای مربوط به نوشتن عارضه(ها) باید نادیده گرفته شوند یا خیر. توجه داشته باشید که این گزینه اندازه واحد تراکنش را بر روی یک عارضه در هر نوبت تنظیم می‌کند که ممکن است هنگام درج در پایگاه‌های داده باعث افت شدید سرعت شود.

آیا مجموعه داده خروجی موجود در حالت به‌روزرسانی باز شود یا خیر.
در نسخه 3.12 اضافه شد.

گونه‌ای از --append که در آن به جای الحاق با OGRLayer::CreateFeature()، از عملیات OGRLayer::UpsertFeature() برای درج یا به‌روزرسانی عوارض استفاده می‌شود.

این قابلیت در حال حاضر تنها در چند درایور پیاده‌سازی شده است: GPKG -- GeoPackage vector، Elasticsearch: Geographically Encoded Objects for Elasticsearch و MongoDBv3 (درایورهایی که upsert را پیاده‌سازی کرده‌اند، قابلیت GDAL_DCAP_UPSERT را ارائه می‌دهند).

عملیات upsert در صورت مقداردهی شدن FID عارضه ورودی (و خالی نبودن نام ستون FID)، از آن به عنوان کلید برای به‌روزرسانی عوارض موجود استفاده می‌کند. بسیار حیاتی است که اطمینان حاصل شود FID در لایه‌های مبدأ و مقصد با یکدیگر سازگار هستند.

برای درایور GPKG، در صورتی که یک ستون UNIQUE وجود داشته باشد که کلید اصلی عدد صحیح (integer primary key) نباشد، انجام upsert برای عوارضی که FID آن‌ها تنظیم نشده یا بی‌اهمیت (non-significant) است نیز امکان‌پذیر است (از گزینه --unset-fid در دستور gdal vector edit می‌توان برای نادیده گرفتن FID عارضه مبدأ استفاده کرد).

غیرفعال کردن نوار پیشرفت و برخی پیام‌های هشدار.

برنامه در صورت موفقیت کد وضعیت ۰ و در صورت بروز خطا مقداری غیر صفر بازمی‌گرداند (خطاهای غیرمسدودکننده که به صورت هشدار صادر می‌شوند، اجرای موفقیت‌آمیز در نظر گرفته می‌شوند).

$ gdal vector sql in.gpkg out.gpkg --output-layer country_sorted_by_pop --sql="SELECT * FROM country ORDER BY pop DESC"

$ gdal vector sql in.gpkg out.gpkg --output-layer=beginning,end --sql="SELECT * FROM my_layer LIMIT 100" --sql="SELECT * FROM my_layer OFFSET 100000 LIMIT 100"

$ gdal vector sql --update my.gpkg --sql "DELETE FROM countries WHERE pop > 1e6"

$ gdal vector sql --update my.gpkg --sql "ALTER TABLE countries ADD COLUMN abbrev STRING(10)"

$ gdal vector pipeline read europe.gpkg ! \
                       sql --sql "SELECT * FROM country WHERE pop > 1e6" ! \
                       write --append --output-layer-name=world world.gpkg

Even Rouault <even.rouault@spatialys.com>

1998-2026

August 18, 2026