نام (NAME)

gdal-vector-partition - افرازبندی مجموعه‌داده برداری به چندین فایل

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

خلاصه دستور (SYNOPSIS)

کاربرد: gdal vector partition [گزینه‌ها] <INPUT> <OUTPUT>
افرازبندی مجموعه‌داده برداری به چندین فایل.
آرگومان‌های موضعی:
  -i, --input <INPUT>                                  مجموعه‌داده‌های برداری ورودی [الزامی] [در خطوط لوله در دسترس نیست]
  -o, --output <OUTPUT>                                دایرکتوری خروجی [الزامی]
گزینه‌های عمومی:
  -h, --help                                           نمایش پیام راهنما و خروج
  --json-usage                                         نمایش شیوه استفاده به صورت سند JSON و خروج
  --config <KEY>=<VALUE>                               گزینه پیکربندی [تکرارپذیر]
  -q, --quiet                                          حالت بی‌صدا (عدم نمایش نوار پیشرفت یا پیام‌های هشدار) [در خطوط لوله در دسترس نیست]
گزینه‌ها:
  --overwrite                                          آیا رونویسی روی مجموعه‌داده خروجی موجود مجاز است
                                                       ناسازگار با --append
  --append                                             آیا الحاق به لایه موجود مجاز است
                                                       ناسازگار با --overwrite
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی
  --co, --creation-option <KEY>=<VALUE>                گزینه ایجاد مجموعه‌داده [تکرارپذیر]
  --lco, --layer-creation-option <KEY>=<VALUE>         گزینه ایجاد لایه [تکرارپذیر]
  --field <FIELD>                                      فیلد(های) توصیفی یا هندسی که افرازبندی بر اساس آن‌ها انجام می‌شود [تکرارپذیر]
  --scheme <SCHEME>                                    طرح افرازبندی. SCHEME=hive|flat (پیش‌فرض: hive)
  --pattern <PATTERN>                                  الگوی نام فایل ('part_%010d' برای طرح hive، و '{LAYER_NAME}_{FIELD_VALUE}_%010d' برای طرح flat)
  --feature-limit <FEATURE-LIMIT>                      حداکثر تعداد عوارض در هر فایل
  --max-file-size <MAX-FILE-SIZE>                      حداکثر اندازه فایل (پسوند MB یا GB قابل استفاده است)
  --omit-partitioned-field                             حذف فیلدهای افراز‌شده از تعریف لایه هدف
  --skip-errors                                        چشم‌پوشی از خطاها هنگام نوشتن عوارض
گزینه‌های پیشرفته:
  --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]

توضیحات (DESCRIPTION)

دستور gdal vector partition عوارض را بسته به مقادیری که در زیرمجموعه‌ای از فیلدهای توصیفی یا هندسی مشخص‌شده توسط کاربر دارند، و/یا با محدود کردن هر لایه خروجی به حداکثر تعداد عوارض و/یا حداکثر اندازه فایل، در فایل‌های مختلف توزیع و تفکیک می‌کند.

دو طرح افرازبندی در دسترس است:

hive، مطابق با Apache Hive partitioning، که طرح پیش‌فرض است.
هر فیلد افرازبندی متناظر با یک دایرکتوری تو در تو است. لایه‌ای با فیلدهای "continent" و "country" را در نظر بگیرید که به عنوان فیلدهای افرازبندی انتخاب شده‌اند. تمام عوارضی که در آن‌ها "continent" برابر با "Europe" و "country" برابر با "France" ارزیابی شود، در زیرپوشه "continent=Europe/country=France/" از دایرکتوری خروجی نوشته خواهند شد.

مقادیر NULL برای فیلدهای افرازبندی به صورت __HIVE_DEFAULT_PARTITION__ در نام پوشه کدگذاری می‌شوند. نویسه‌های غیر ASCII، فاصله، علامت مساوی، یا نویسه‌هایی که با محدودیت‌های نام پوشه سازگار نیستند به صورت درصدی (Percent-encoding) کدگذاری می‌شوند (برای نمونه %20 برای فاصله).
flat که در آن فایل‌ها مستقیماً در زیر دایرکتوری خروجی با استفاده از یک الگوی نام فایل پیش‌فرض {LAYER_NAME}_{FIELD_VALUE}_%10d نوشته می‌شوند.

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

دستور gdal vector partition می‌تواند به عنوان آخرین مرحله یک خط لوله (Pipeline) استفاده شود.

گزینه‌های زیر در دسترس هستند:

گزینه‌های اختصاصی برنامه (PROGRAM-SPECIFIC OPTIONS)

--feature-limit <FEATURE-LIMIT>: حداکثر تعداد عوارض در هر فایل. به طور پیش‌فرض، نامحدود است. در صورت فراتر رفتن از این حد، چندین پارت (بخش) ایجاد می‌شود.

--field <FIELD-NAME>

فیلد(های) مبنا برای افرازبندی.

فقط فیلدهای توصیفی از نوع String، Integer و Integer64 مجاز هستند. ترتیب مشخص کردن فیلدها در تعیین سلسله‌مراتب پوشه‌ها اهمیت دارد.

از نگارش GDAL 3.13 به بعد، می‌توان نام فیلدهای هندسی را نیز مشخص کرد (OGR_GEOMETRY نام عمومی برای نخستین فیلد هندسه است). افرازبندی روی فیلدهای هندسی بر اساس نوع هندسه انجام می‌شود. این ویژگی برای قالب‌های فایلی که در هر لایه تنها یک نوع هندسه را مجاز می‌دانند مفید است.

از نگارش GDAL 3.13 به بعد، مشخص کردن --field دیگر الزامی نیست، اما در صورت عدم تعیین آن، باید --feature-limit و/یا --max-file-size مشخص شوند.

--max-file-size <MAX-FILE-SIZE>: حداکثر اندازه فایل (پسوندهای MB یا GB قابل استفاده هستند). به طور پیش‌فرض، نامحدود است. در صورت فراتر رفتن از این حد، چندین پارت ایجاد می‌شود.
توجه داشته باشید که حداکثر اندازه فایل به عنوان یک راهنما (Hint) استفاده می‌شود و ممکن است دقیقاً رعایت نشود؛ زیرا ارزیابی اندازه فایل متناظر با یک عارضه بر مبنای روش‌های اکتشافی (Heuristics) است، چرا که اندازه خود فایل در حین نوشتن به طور قابل اعتماد قابل استفاده نیست. به‌ویژه، این روش‌های اکتشافی هیچ‌گونه فشرده‌سازی را فرض نمی‌گیرند، بنابراین برای قالب‌های فشرده‌شده، اندازه واقعی یک پارت می‌تواند به مراتب کوچک‌تر از حد مشخص‌شده باشد.

--omit-partitioned-field: تعیین اینکه آیا فیلدهای افراز‌شده از تعریف لایه مقصد حذف شوند یا خیر. برای قالب خروجی Parquet و افرازبندی Hive به طور خودکار فعال می‌شود.

--output <OUTPUT-DIRECTORY>: ریشه دایرکتوری خروجی. [الزامی]

--pattern <PATTERN>: الگوی نام فایل. یک رشته به انتخاب کاربر با جایگزینی‌های زیر:

{LAYER_NAME}، در صورت وجود، با نام لایه جایگزین می‌شود (در صورت نیاز کدگذاری درصدی می‌شود).
{FIELD_VALUE}، در صورت وجود، با مقدار فیلد افرازبندی جایگزین می‌شود (در صورت نیاز کدگذاری درصدی می‌شود). اگر از چند فیلد افرازبندی استفاده شود، هر مقدار با زیرخط (_) جدا می‌شود. رشته‌های خالی با __EMPTY__ و فیلدهای خالی (Null) با __NULL__ جایگزین می‌شوند.
%[0?][0-9]?[0]?d: قالب‌بندی عدد صحیح به سبک زبان C برای شماره پارت. مقادیر معتبر برای نمونه %d یا %05d هستند. باید دقیقاً یک و تنها یک مشخص‌کننده شماره پارت در الگو وجود داشته باشد.

مقادیر پیش‌فرض برای الگو برابر با part_%010d برای طرح hive، و {LAYER_NAME}_{FIELD_VALUE}_%010d برای طرح flat است.

--scheme hive|flat: طرح افرازبندی. پیش‌فرض hive است.

گزینه‌های استاندارد (STANDARD OPTIONS)

--append: تعیین اینکه آیا دایرکتوری خروجی باید در حالت الحاق باز شود یا خیر. این امر مستلزم آن است که دایرکتوری از قبل وجود داشته باشد و قالب خروجی نیز از الحاق پشتیبانی کند.
این حالت هنگام افزودن عوارض جدید به یک مجموعه‌داده افراز‌شده موجود مفید است.

--co, --creation-option <NAME>=<VALUE>

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

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

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

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

--if, --input-format <format>: نام قالب/درایور برای تلاش جهت باز کردن فایل(های) ورودی. معمولاً نیازی به مشخص کردن آن نیست، اما می‌توان از آن برای چشم‌پوشی از تشخیص خودکار درایور در مواردی که در انتخاب درایور مناسب ناموفق است استفاده کرد. این گزینه می‌تواند چندین بار تکرار شود تا چند درایور نامزد مشخص گردند. توجه داشته باشید که این گزینه آن درایورها را مجبور به باز کردن مجموعه‌داده نمی‌کند. به‌ویژه، برخی درایورها نیازمندی‌هایی درباره پسوند فایل دارند.
می‌تواند تکرار شود.

--lco, --layer-creation-option <NAME>=<VALUE>

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

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

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

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

--oo, --open-option <NAME>=<VALUE>: گزینه باز کردن مجموعه‌داده (مختص هر قالب).
می‌تواند تکرار شود.

-f, --of, --format, --output-format <OUTPUT-FORMAT>: تعیین قالب برداری خروجی مورد استفاده. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: gdal --formats | grep vector | grep rw | sort

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

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

کد وضعیت بازگشتی (RETURN STATUS CODE)

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

مثال‌ها (EXAMPLES)

مثال ۱: ایجاد یک افراز بر پایه فیلدهای "continent" و "country"

$ gdal vector partition world_cities.gpkg out_directory --field continent,country --format Parquet

مثال ۲: ایجاد یک افراز بر پایه فیلد "country"، با فیلتر روی شهرهای با جمعیت بیش از ۱ میلیون نفر، با طرح افرازبندی مسطح (flat)

$ gdal pipeline ! read world_cities.gpkg ! filter --where "pop > 1e6" ! partition out_directory --field country --format GPKG --scheme flat

مثال ۳: ایجاد چندین Shapefile، یکی برای هر نوع هندسه، از یک فایل GeoPackage، با گروه‌بندی POLYGON/MULTIPOLYGON یا LINESTRING/MULTILINESTRING.

$ gdal vector pipeline ! read input.gpkg ! set-geom-type --multi ! partition out_directory --scheme flat --field OGR_GEOMETRY --format "ESRI Shapefile"

مثال ۴: تقسیم یک فایل به فایل‌هایی با حداکثر ۱۰۰٬۰۰۰ عارضه.

$ gdal vector partition world_cities.gpkg out_directory --feature-limit 100000 --scheme flat --format Parquet

مثال ۵: مرتب‌سازی مکانی یک فایل و تقسیم آن به فایل‌هایی با حداکثر ۱۰۰٬۰۰۰ عارضه.

$ gdal vector pipeline read world_cities.gpkg ! sort ! partition out_directory --feature-limit 100000 --scheme flat --format Parquet

نویسندگان (AUTHORS)

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026