{"id":5593,"date":"2026-02-12T20:44:52","date_gmt":"2026-02-13T01:44:52","guid":{"rendered":"https:\/\/chubes.net\/?documentation=wp_usermeta"},"modified":"2026-03-13T03:28:17","modified_gmt":"2026-03-13T07:28:17","slug":"wp_usermeta","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/wordpress-core\/database-schema\/wp_usermeta\/","title":{"rendered":"wp_usermeta"},"content":{"rendered":"<p>Key-value storage for user metadata. Stores capabilities, preferences, and custom user data.<\/p><h2 class=\"wp-block-heading\">Schema<\/h2><figure class=\"wp-block-table\"><table><thead><tr><th>Column<\/th><th>Type<\/th><th>Null<\/th><th>Default<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>umeta_id<\/code><\/td><td>bigint(20) unsigned<\/td><td>NO<\/td><td>auto_increment<\/td><td>Unique identifier for the meta entry<\/td><\/tr><tr><td><code>user_id<\/code><\/td><td>bigint(20) unsigned<\/td><td>NO<\/td><td>0<\/td><td>Associated user ID (FK \u2192 wp_users.ID)<\/td><\/tr><tr><td><code>meta_key<\/code><\/td><td>varchar(255)<\/td><td>YES<\/td><td>NULL<\/td><td>Meta key name<\/td><\/tr><tr><td><code>meta_value<\/code><\/td><td>longtext<\/td><td>YES<\/td><td>NULL<\/td><td>Meta value (can be serialized)<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Indexes<\/h2><figure class=\"wp-block-table\"><table><thead><tr><th>Key Name<\/th><th>Columns<\/th><th>Unique<\/th><th>Purpose<\/th><\/tr><\/thead><tbody><tr><td><code>PRIMARY<\/code><\/td><td>umeta_id<\/td><td>Yes<\/td><td>Primary key<\/td><\/tr><tr><td><code>user_id<\/code><\/td><td>user_id<\/td><td>No<\/td><td>All meta for a user<\/td><\/tr><tr><td><code>meta_key<\/code><\/td><td>meta_key(191)<\/td><td>No<\/td><td>Lookup by key name<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Foreign Key Relationships<\/h2><ul class=\"wp-block-list\"><li><code>user_id<\/code> \u2192 <code>wp_users.ID<\/code> (the user this meta belongs to)<\/li><\/ul><h2 class=\"wp-block-heading\">Core Meta Keys<\/h2><h3 class=\"wp-block-heading\">Authentication &amp; Capabilities<\/h3><figure class=\"wp-block-table\"><table><thead><tr><th>Key<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>wp_capabilities<\/code><\/td><td>Serialized array of role(s) \u2192 true<\/td><\/tr><tr><td><code>wp_user_level<\/code><\/td><td>Deprecated numeric user level (0-10)<\/td><\/tr><tr><td><code>session_tokens<\/code><\/td><td>Active login sessions<\/td><\/tr><\/tbody><\/table><\/figure><h3 class=\"wp-block-heading\">Profile Information<\/h3><figure class=\"wp-block-table\"><table><thead><tr><th>Key<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>nickname<\/code><\/td><td>User&#8217;s nickname<\/td><\/tr><tr><td><code>first_name<\/code><\/td><td>First name<\/td><\/tr><tr><td><code>last_name<\/code><\/td><td>Last name<\/td><\/tr><tr><td><code>description<\/code><\/td><td>Biographical info<\/td><\/tr><\/tbody><\/table><\/figure><h3 class=\"wp-block-heading\">Preferences<\/h3><figure class=\"wp-block-table\"><table><thead><tr><th>Key<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>admin_color<\/code><\/td><td>Admin color scheme<\/td><\/tr><tr><td><code>use_ssl<\/code><\/td><td>Force SSL on admin<\/td><\/tr><tr><td><code>show_admin_bar_front<\/code><\/td><td>Show admin bar on frontend<\/td><\/tr><tr><td><code>locale<\/code><\/td><td>User-specific locale<\/td><\/tr><tr><td><code>rich_editing<\/code><\/td><td>Use visual editor<\/td><\/tr><tr><td><code>syntax_highlighting<\/code><\/td><td>Code syntax highlighting<\/td><\/tr><tr><td><code>comment_shortcuts<\/code><\/td><td>Keyboard shortcuts for comments<\/td><\/tr><\/tbody><\/table><\/figure><h3 class=\"wp-block-heading\">Dashboard &amp; Admin<\/h3><figure class=\"wp-block-table\"><table><thead><tr><th>Key<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>dismissed_wp_pointers<\/code><\/td><td>Dismissed admin pointers<\/td><\/tr><tr><td><code>wp_dashboard_quick_press_last_post_id<\/code><\/td><td>Quick Draft post ID<\/td><\/tr><tr><td><code>community-events-location<\/code><\/td><td>Dashboard events location<\/td><\/tr><tr><td><code>closedpostboxes_*<\/code><\/td><td>Collapsed metaboxes<\/td><\/tr><tr><td><code>metaboxhidden_*<\/code><\/td><td>Hidden metaboxes<\/td><\/tr><tr><td><code>screen_layout_*<\/code><\/td><td>Screen column layout<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Capabilities Format<\/h2><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">\/\/ wp_capabilities value (serialized)\na:1:{s:13:&quot;administrator&quot;;b:1;}\n\n\/\/ Decoded\n[&#039;administrator&#039; =&gt; true]<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Common Queries<\/h2><h3 class=\"wp-block-heading\">Get all meta for a user<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">sql<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-sql\"><code class=\"language-sql\">SELECT meta_key, meta_value \nFROM wp_usermeta \nWHERE user_id = 1;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Get specific meta value<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">sql<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-sql\"><code class=\"language-sql\">SELECT meta_value \nFROM wp_usermeta \nWHERE user_id = 1 \n  AND meta_key = &#039;first_name&#039;;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Get all administrators<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">sql<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-sql\"><code class=\"language-sql\">SELECT u.* \nFROM wp_users u\nJOIN wp_usermeta um ON u.ID = um.user_id\nWHERE um.meta_key = &#039;wp_capabilities&#039; \n  AND um.meta_value LIKE &#039;%administrator%&#039;;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Get users with specific meta<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">sql<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-sql\"><code class=\"language-sql\">SELECT u.*, um.meta_value as custom_field\nFROM wp_users u\nJOIN wp_usermeta um ON u.ID = um.user_id\nWHERE um.meta_key = &#039;my_custom_field&#039;;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Delete orphaned usermeta<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">sql<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-sql\"><code class=\"language-sql\">DELETE um FROM wp_usermeta um\nLEFT JOIN wp_users u ON um.user_id = u.ID\nWHERE u.ID IS NULL;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Count users by role<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">sql<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-sql\"><code class=\"language-sql\">SELECT \n  CASE \n    WHEN meta_value LIKE &#039;%administrator%&#039; THEN &#039;administrator&#039;\n    WHEN meta_value LIKE &#039;%editor%&#039; THEN &#039;editor&#039;\n    WHEN meta_value LIKE &#039;%author%&#039; THEN &#039;author&#039;\n    WHEN meta_value LIKE &#039;%contributor%&#039; THEN &#039;contributor&#039;\n    WHEN meta_value LIKE &#039;%subscriber%&#039; THEN &#039;subscriber&#039;\n    ELSE &#039;other&#039;\n  END as role,\n  COUNT(*) as count\nFROM wp_usermeta\nWHERE meta_key = &#039;wp_capabilities&#039;\nGROUP BY role;<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">WordPress API Functions<\/h2><ul class=\"wp-block-list\"><li><code>get_user_meta( $user_id, $key, $single )<\/code> &#8211; Get meta value(s)<\/li><li><code>add_user_meta( $user_id, $key, $value, $unique )<\/code> &#8211; Add meta<\/li><li><code>update_user_meta( $user_id, $key, $value )<\/code> &#8211; Update meta<\/li><li><code>delete_user_meta( $user_id, $key, $value )<\/code> &#8211; Delete meta<\/li><li><code>get_user_option( $option, $user_id )<\/code> &#8211; Get user option<\/li><li><code>update_user_option( $user_id, $option, $value )<\/code> &#8211; Update user option<\/li><\/ul><h2 class=\"wp-block-heading\">Multisite Notes<\/h2><p>In multisite, capabilities use the blog prefix:<\/p><ul class=\"wp-block-list\"><li><code>wp_capabilities<\/code> \u2192 single site or main site<\/li><li><code>wp_2_capabilities<\/code> \u2192 site ID 2<\/li><li><code>wp_3_capabilities<\/code> \u2192 site ID 3<\/li><\/ul><p>The <code>{$prefix}_user_level<\/code> follows the same pattern.<\/p><h2 class=\"wp-block-heading\">Performance Notes<\/h2><ul class=\"wp-block-list\"><li>Session tokens can grow large with many active sessions<\/li><li>Stale session data should be periodically cleaned<\/li><li>Use <code>get_user_meta()<\/code> with <code>$single = true<\/code> when expecting one value<\/li><\/ul>","protected":false},"excerpt":{"rendered":"<p>Key-value storage for user metadata. Stores capabilities, preferences, and custom user data. Schema Column Type Null Default Description umeta_id bigint(20) unsigned NO auto_increment Unique identifier for the meta entry user_id&#8230;<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[611],"project_type":[749],"class_list":["post-5593","documentation","type-documentation","status-publish","hentry","project-database-schema","project_type-wordpress-reference"],"project_info":{"id":589,"name":"WordPress Core","slug":"wordpress-core"},"project_type_info":{"id":749,"name":"WordPress Reference","slug":"wordpress-reference"},"_links":{"self":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5593","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation"}],"about":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/types\/documentation"}],"version-history":[{"count":3,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5593\/revisions"}],"predecessor-version":[{"id":8931,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5593\/revisions\/8931"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=5593"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=5593"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=5593"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=5593"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}