| 1 |
/*------------------------------------------------------------------------- |
| 2 |
* |
| 3 |
* amutils.c |
| 4 |
* SQL-level APIs related to index access methods. |
| 5 |
* |
| 6 |
* Copyright (c) 2016-2025, PostgreSQL Global Development Group |
| 7 |
* |
| 8 |
* |
| 9 |
* IDENTIFICATION |
| 10 |
* src/backend/utils/adt/amutils.c |
| 11 |
* |
| 12 |
*------------------------------------------------------------------------- |
| 13 |
*/ |
| 14 |
#include "postgres.h" |
| 15 |
|
| 16 |
#include "access/amapi.h" |
| 17 |
#include "access/htup_details.h" |
| 18 |
#include "catalog/pg_class.h" |
| 19 |
#include "catalog/pg_index.h" |
| 20 |
#include "utils/builtins.h" |
| 21 |
#include "utils/syscache.h" |
| 22 |
|
| 23 |
|
| 24 |
/* Convert string property name to enum, for efficiency */ |
| 25 |
struct am_propname |
| 26 |
{ |
| 27 |
const char *name; |
| 28 |
IndexAMProperty prop; |
| 29 |
}; |
| 30 |
|
| 31 |
static const struct am_propname am_propnames[] = |
| 32 |
{ |
| 33 |
{ |
| 34 |
"asc", AMPROP_ASC |
| 35 |
}, |
| 36 |
{ |
| 37 |
"desc", AMPROP_DESC |
| 38 |
}, |
| 39 |
{ |
| 40 |
"nulls_first", AMPROP_NULLS_FIRST |
| 41 |
}, |
| 42 |
{ |
| 43 |
"nulls_last", AMPROP_NULLS_LAST |
| 44 |
}, |
| 45 |
{ |
| 46 |
"orderable", AMPROP_ORDERABLE |
| 47 |
}, |
| 48 |
{ |
| 49 |
"distance_orderable", AMPROP_DISTANCE_ORDERABLE |
| 50 |
}, |
| 51 |
{ |
| 52 |
"returnable", AMPROP_RETURNABLE |
| 53 |
}, |
| 54 |
{ |
| 55 |
"search_array", AMPROP_SEARCH_ARRAY |
| 56 |
}, |
| 57 |
{ |
| 58 |
"search_nulls", AMPROP_SEARCH_NULLS |
| 59 |
}, |
| 60 |
{ |
| 61 |
"clusterable", AMPROP_CLUSTERABLE |
| 62 |
}, |
| 63 |
{ |
| 64 |
"index_scan", AMPROP_INDEX_SCAN |
| 65 |
}, |
| 66 |
{ |
| 67 |
"bitmap_scan", AMPROP_BITMAP_SCAN |
| 68 |
}, |
| 69 |
{ |
| 70 |
"backward_scan", AMPROP_BACKWARD_SCAN |
| 71 |
}, |
| 72 |
{ |
| 73 |
"can_order", AMPROP_CAN_ORDER |
| 74 |
}, |
| 75 |
{ |
| 76 |
"can_unique", AMPROP_CAN_UNIQUE |
| 77 |
}, |
| 78 |
{ |
| 79 |
"can_multi_col", AMPROP_CAN_MULTI_COL |
| 80 |
}, |
| 81 |
{ |
| 82 |
"can_exclude", AMPROP_CAN_EXCLUDE |
| 83 |
}, |
| 84 |
{ |
| 85 |
"can_include", AMPROP_CAN_INCLUDE |
| 86 |
}, |
| 87 |
}; |
| 88 |
|
| 89 |
static IndexAMProperty |
| 90 |
lookup_prop_name(const char *name) |
| 91 |
{ |
| 92 |
int i; |
| 93 |
|
| 94 |
for (i = 0; i < lengthof(am_propnames); i++) |
| 95 |
{ |
| 96 |
if (pg_strcasecmp(am_propnames[i].name, name) == 0) |
| 97 |
return am_propnames[i].prop; |
| 98 |
} |
| 99 |
|
| 100 |
/* We do not throw an error, so that AMs can define their own properties */ |
| 101 |
return AMPROP_UNKNOWN; |
| 102 |
} |
| 103 |
|
| 104 |
/* |
| 105 |
* Common code for properties that are just bit tests of indoptions. |
| 106 |
* |
| 107 |
* tuple: the pg_index heaptuple |
| 108 |
* attno: identify the index column to test the indoptions of. |
| 109 |
* guard: if false, a boolean false result is forced (saves code in caller). |
| 110 |
* iopt_mask: mask for interesting indoption bit. |
| 111 |
* iopt_expect: value for a "true" result (should be 0 or iopt_mask). |
| 112 |
* |
| 113 |
* Returns false to indicate a NULL result (for "unknown/inapplicable"), |
| 114 |
* otherwise sets *res to the boolean value to return. |
| 115 |
*/ |
| 116 |
static bool |
| 117 |
test_indoption(HeapTuple tuple, int attno, bool guard, |
| 118 |
int16 iopt_mask, int16 iopt_expect, |
| 119 |
bool *res) |
| 120 |
{ |
| 121 |
Datum datum; |
| 122 |
int2vector *indoption; |
| 123 |
int16 indoption_val; |
| 124 |
|
| 125 |
if (!guard) |
| 126 |
{ |
| 127 |
*res = false; |
| 128 |
return true; |
| 129 |
} |
| 130 |
|
| 131 |
datum = SysCacheGetAttrNotNull(INDEXRELID, tuple, Anum_pg_index_indoption); |
| 132 |
|
| 133 |
indoption = ((int2vector *) DatumGetPointer(datum)); |
| 134 |
indoption_val = indoption->values[attno - 1]; |
| 135 |
|
| 136 |
*res = (indoption_val & iopt_mask) == iopt_expect; |
| 137 |
|
| 138 |
return true; |
| 139 |
} |
| 140 |
|
| 141 |
|
| 142 |
/* |
| 143 |
* Test property of an index AM, index, or index column. |
| 144 |
* |
| 145 |
* This is common code for different SQL-level funcs, so the amoid and |
| 146 |
* index_oid parameters are mutually exclusive; we look up the amoid from the |
| 147 |
* index_oid if needed, or if no index oid is given, we're looking at AM-wide |
| 148 |
* properties. |
| 149 |
*/ |
| 150 |
static Datum |
| 151 |
indexam_property(FunctionCallInfo fcinfo, |
| 152 |
const char *propname, |
| 153 |
Oid amoid, Oid index_oid, int attno) |
| 154 |
{ |
| 155 |
bool res = false; |
| 156 |
bool isnull = false; |
| 157 |
int natts = 0; |
| 158 |
IndexAMProperty prop; |
| 159 |
IndexAmRoutine *routine; |
| 160 |
|
| 161 |
/* Try to convert property name to enum (no error if not known) */ |
| 162 |
prop = lookup_prop_name(propname); |
| 163 |
|
| 164 |
/* If we have an index OID, look up the AM, and get # of columns too */ |
| 165 |
if (OidIsValid(index_oid)) |
| 166 |
{ |
| 167 |
HeapTuple tuple; |
| 168 |
Form_pg_class rd_rel; |
| 169 |
|
| 170 |
Assert(!OidIsValid(amoid)); |
| 171 |
tuple = SearchSysCache1(RELOID, ObjectIdGetDatum(index_oid)); |
| 172 |
if (!HeapTupleIsValid(tuple)) |
| 173 |
PG_RETURN_NULL(); |
| 174 |
rd_rel = (Form_pg_class) GETSTRUCT(tuple); |
| 175 |
if (rd_rel->relkind != RELKIND_INDEX && |
| 176 |
rd_rel->relkind != RELKIND_PARTITIONED_INDEX) |
| 177 |
{ |
| 178 |
ReleaseSysCache(tuple); |
| 179 |
PG_RETURN_NULL(); |
| 180 |
} |
| 181 |
amoid = rd_rel->relam; |
| 182 |
natts = rd_rel->relnatts; |
| 183 |
ReleaseSysCache(tuple); |
| 184 |
} |
| 185 |
|
| 186 |
/* |
| 187 |
* At this point, either index_oid == InvalidOid or it's a valid index |
| 188 |
* OID. Also, after this test and the one below, either attno == 0 for |
| 189 |
* index-wide or AM-wide tests, or it's a valid column number in a valid |
| 190 |
* index. |
| 191 |
*/ |
| 192 |
if (attno < 0 || attno > natts) |
| 193 |
PG_RETURN_NULL(); |
| 194 |
|
| 195 |
/* |
| 196 |
* Get AM information. If we don't have a valid AM OID, return NULL. |
| 197 |
*/ |
| 198 |
routine = GetIndexAmRoutineByAmId(amoid, true); |
| 199 |
if (routine == NULL) |
| 200 |
PG_RETURN_NULL(); |
| 201 |
|
| 202 |
/* |
| 203 |
* If there's an AM property routine, give it a chance to override the |
| 204 |
* generic logic. Proceed if it returns false. |
| 205 |
*/ |
| 206 |
if (routine->amproperty && |
| 207 |
routine->amproperty(index_oid, attno, prop, propname, |
| 208 |
&res, &isnull)) |
| 209 |
{ |
| 210 |
if (isnull) |
| 211 |
PG_RETURN_NULL(); |
| 212 |
PG_RETURN_BOOL(res); |
| 213 |
} |
| 214 |
|
| 215 |
if (attno > 0) |
| 216 |
{ |
| 217 |
HeapTuple tuple; |
| 218 |
Form_pg_index rd_index; |
| 219 |
bool iskey = true; |
| 220 |
|
| 221 |
/* |
| 222 |
* Handle column-level properties. Many of these need the pg_index row |
| 223 |
* (which we also need to use to check for nonkey atts) so we fetch |
| 224 |
* that first. |
| 225 |
*/ |
| 226 |
tuple = SearchSysCache1(INDEXRELID, ObjectIdGetDatum(index_oid)); |
| 227 |
if (!HeapTupleIsValid(tuple)) |
| 228 |
PG_RETURN_NULL(); |
| 229 |
rd_index = (Form_pg_index) GETSTRUCT(tuple); |
| 230 |
|
| 231 |
Assert(index_oid == rd_index->indexrelid); |
| 232 |
Assert(attno > 0 && attno <= rd_index->indnatts); |
| 233 |
|
| 234 |
isnull = true; |
| 235 |
|
| 236 |
/* |
| 237 |
* If amcaninclude, we might be looking at an attno for a nonkey |
| 238 |
* column, for which we (generically) assume that most properties are |
| 239 |
* null. |
| 240 |
*/ |
| 241 |
if (routine->amcaninclude |
| 242 |
&& attno > rd_index->indnkeyatts) |
| 243 |
iskey = false; |
| 244 |
|
| 245 |
switch (prop) |
| 246 |
{ |
| 247 |
case AMPROP_ASC: |
| 248 |
if (iskey && |
| 249 |
test_indoption(tuple, attno, routine->amcanorder, |
| 250 |
INDOPTION_DESC, 0, &res)) |
| 251 |
isnull = false; |
| 252 |
break; |
| 253 |
|
| 254 |
case AMPROP_DESC: |
| 255 |
if (iskey && |
| 256 |
test_indoption(tuple, attno, routine->amcanorder, |
| 257 |
INDOPTION_DESC, INDOPTION_DESC, &res)) |
| 258 |
isnull = false; |
| 259 |
break; |
| 260 |
|
| 261 |
case AMPROP_NULLS_FIRST: |
| 262 |
if (iskey && |
| 263 |
test_indoption(tuple, attno, routine->amcanorder, |
| 264 |
INDOPTION_NULLS_FIRST, INDOPTION_NULLS_FIRST, &res)) |
| 265 |
isnull = false; |
| 266 |
break; |
| 267 |
|
| 268 |
case AMPROP_NULLS_LAST: |
| 269 |
if (iskey && |
| 270 |
test_indoption(tuple, attno, routine->amcanorder, |
| 271 |
INDOPTION_NULLS_FIRST, 0, &res)) |
| 272 |
isnull = false; |
| 273 |
break; |
| 274 |
|
| 275 |
case AMPROP_ORDERABLE: |
| 276 |
|
| 277 |
/* |
| 278 |
* generic assumption is that nonkey columns are not orderable |
| 279 |
*/ |
| 280 |
res = iskey ? routine->amcanorder : false; |
| 281 |
isnull = false; |
| 282 |
break; |
| 283 |
|
| 284 |
case AMPROP_DISTANCE_ORDERABLE: |
| 285 |
|
| 286 |
/* |
| 287 |
* The conditions for whether a column is distance-orderable |
| 288 |
* are really up to the AM (at time of writing, only GiST |
| 289 |
* supports it at all). The planner has its own idea based on |
| 290 |
* whether it finds an operator with amoppurpose 'o', but |
| 291 |
* getting there from just the index column type seems like a |
| 292 |
* lot of work. So instead we expect the AM to handle this in |
| 293 |
* its amproperty routine. The generic result is to return |
| 294 |
* false if the AM says it never supports this, or if this is |
| 295 |
* a nonkey column, and null otherwise (meaning we don't |
| 296 |
* know). |
| 297 |
*/ |
| 298 |
if (!iskey || !routine->amcanorderbyop) |
| 299 |
{ |
| 300 |
res = false; |
| 301 |
isnull = false; |
| 302 |
} |
| 303 |
break; |
| 304 |
|
| 305 |
case AMPROP_RETURNABLE: |
| 306 |
|
| 307 |
/* note that we ignore iskey for this property */ |
| 308 |
|
| 309 |
isnull = false; |
| 310 |
res = false; |
| 311 |
|
| 312 |
if (routine->amcanreturn) |
| 313 |
{ |
| 314 |
/* |
| 315 |
* If possible, the AM should handle this test in its |
| 316 |
* amproperty function without opening the rel. But this |
| 317 |
* is the generic fallback if it does not. |
| 318 |
*/ |
| 319 |
Relation indexrel = index_open(index_oid, AccessShareLock); |
| 320 |
|
| 321 |
res = index_can_return(indexrel, attno); |
| 322 |
index_close(indexrel, AccessShareLock); |
| 323 |
} |
| 324 |
break; |
| 325 |
|
| 326 |
case AMPROP_SEARCH_ARRAY: |
| 327 |
if (iskey) |
| 328 |
{ |
| 329 |
res = routine->amsearcharray; |
| 330 |
isnull = false; |
| 331 |
} |
| 332 |
break; |
| 333 |
|
| 334 |
case AMPROP_SEARCH_NULLS: |
| 335 |
if (iskey) |
| 336 |
{ |
| 337 |
res = routine->amsearchnulls; |
| 338 |
isnull = false; |
| 339 |
} |
| 340 |
break; |
| 341 |
|
| 342 |
default: |
| 343 |
break; |
| 344 |
} |
| 345 |
|
| 346 |
ReleaseSysCache(tuple); |
| 347 |
|
| 348 |
if (!isnull) |
| 349 |
PG_RETURN_BOOL(res); |
| 350 |
PG_RETURN_NULL(); |
| 351 |
} |
| 352 |
|
| 353 |
if (OidIsValid(index_oid)) |
| 354 |
{ |
| 355 |
/* |
| 356 |
* Handle index-level properties. Currently, these only depend on the |
| 357 |
* AM, but that might not be true forever, so we make users name an |
| 358 |
* index not just an AM. |
| 359 |
*/ |
| 360 |
switch (prop) |
| 361 |
{ |
| 362 |
case AMPROP_CLUSTERABLE: |
| 363 |
PG_RETURN_BOOL(routine->amclusterable); |
| 364 |
|
| 365 |
case AMPROP_INDEX_SCAN: |
| 366 |
PG_RETURN_BOOL(routine->amgettuple ? true : false); |
| 367 |
|
| 368 |
case AMPROP_BITMAP_SCAN: |
| 369 |
PG_RETURN_BOOL(routine->amgetbitmap ? true : false); |
| 370 |
|
| 371 |
case AMPROP_BACKWARD_SCAN: |
| 372 |
PG_RETURN_BOOL(routine->amcanbackward); |
| 373 |
|
| 374 |
default: |
| 375 |
PG_RETURN_NULL(); |
| 376 |
} |
| 377 |
} |
| 378 |
|
| 379 |
/* |
| 380 |
* Handle AM-level properties (those that control what you can say in |
| 381 |
* CREATE INDEX). |
| 382 |
*/ |
| 383 |
switch (prop) |
| 384 |
{ |
| 385 |
case AMPROP_CAN_ORDER: |
| 386 |
PG_RETURN_BOOL(routine->amcanorder); |
| 387 |
|
| 388 |
case AMPROP_CAN_UNIQUE: |
| 389 |
PG_RETURN_BOOL(routine->amcanunique); |
| 390 |
|
| 391 |
case AMPROP_CAN_MULTI_COL: |
| 392 |
PG_RETURN_BOOL(routine->amcanmulticol); |
| 393 |
|
| 394 |
case AMPROP_CAN_EXCLUDE: |
| 395 |
PG_RETURN_BOOL(routine->amgettuple ? true : false); |
| 396 |
|
| 397 |
case AMPROP_CAN_INCLUDE: |
| 398 |
PG_RETURN_BOOL(routine->amcaninclude); |
| 399 |
|
| 400 |
default: |
| 401 |
PG_RETURN_NULL(); |
| 402 |
} |
| 403 |
} |
| 404 |
|
| 405 |
/* |
| 406 |
* Test property of an AM specified by AM OID |
| 407 |
*/ |
| 408 |
Datum |
| 409 |
pg_indexam_has_property(PG_FUNCTION_ARGS) |
| 410 |
{ |
| 411 |
Oid amoid = PG_GETARG_OID(0); |
| 412 |
char *propname = text_to_cstring(PG_GETARG_TEXT_PP(1)); |
| 413 |
|
| 414 |
return indexam_property(fcinfo, propname, amoid, InvalidOid, 0); |
| 415 |
} |
| 416 |
|
| 417 |
/* |
| 418 |
* Test property of an index specified by index OID |
| 419 |
*/ |
| 420 |
Datum |
| 421 |
pg_index_has_property(PG_FUNCTION_ARGS) |
| 422 |
{ |
| 423 |
Oid relid = PG_GETARG_OID(0); |
| 424 |
char *propname = text_to_cstring(PG_GETARG_TEXT_PP(1)); |
| 425 |
|
| 426 |
return indexam_property(fcinfo, propname, InvalidOid, relid, 0); |
| 427 |
} |
| 428 |
|
| 429 |
/* |
| 430 |
* Test property of an index column specified by index OID and column number |
| 431 |
*/ |
| 432 |
Datum |
| 433 |
pg_index_column_has_property(PG_FUNCTION_ARGS) |
| 434 |
{ |
| 435 |
Oid relid = PG_GETARG_OID(0); |
| 436 |
int32 attno = PG_GETARG_INT32(1); |
| 437 |
char *propname = text_to_cstring(PG_GETARG_TEXT_PP(2)); |
| 438 |
|
| 439 |
/* Reject attno 0 immediately, so that attno > 0 identifies this case */ |
| 440 |
if (attno <= 0) |
| 441 |
PG_RETURN_NULL(); |
| 442 |
|
| 443 |
return indexam_property(fcinfo, propname, InvalidOid, relid, attno); |
| 444 |
} |
| 445 |
|
| 446 |
/* |
| 447 |
* Return the name of the given phase, as used for progress reporting by the |
| 448 |
* given AM. |
| 449 |
*/ |
| 450 |
Datum |
| 451 |
pg_indexam_progress_phasename(PG_FUNCTION_ARGS) |
| 452 |
{ |
| 453 |
Oid amoid = PG_GETARG_OID(0); |
| 454 |
int32 phasenum = PG_GETARG_INT32(1); |
| 455 |
IndexAmRoutine *routine; |
| 456 |
char *name; |
| 457 |
|
| 458 |
routine = GetIndexAmRoutineByAmId(amoid, true); |
| 459 |
if (routine == NULL || !routine->ambuildphasename) |
| 460 |
PG_RETURN_NULL(); |
| 461 |
|
| 462 |
name = routine->ambuildphasename(phasenum); |
| 463 |
if (!name) |
| 464 |
PG_RETURN_NULL(); |
| 465 |
|
| 466 |
PG_RETURN_DATUM(CStringGetTextDatum(name)); |
| 467 |
} |