delete_post_meta() │ WP 1.5.0

Deletes all custom fields (meta-fields) with the specified key for the specified post.

Use delete_post_meta_by_key() to delete meta-fields by key for all posts.

Uses: delete_metadata()
Used By: update_attached_file(), set_post_thumbnail(), wp_update_attachment_metadata()

No Hooks.

Returns

true|false. true on successful deletion, false otherwise.

Usage

delete_post_meta( $post_id, $key, $value );
$post_id(integer) (required)
ID of the post whose custom fields need to be deleted.
$key(string) (required)
Key of the custom field to be deleted.
$value(string)
Value of the custom field to be deleted. Specifying this parameter may be useful when a post has multiple custom fields with the same keys. If left empty, all custom fields with the specified key will be deleted.
Default: ''

Examples

1

#1 Deleting specified meta-fields (custom fields)

Suppose we were using a plugin that added custom fields to every post, and now we've abandoned that plugin and need to remove all custom fields that were created by that plugin.

The plugin created fields with the keys keys related_posts and post_inspiration

To remove all these custom fields, you can use this code:

$allposts = get_posts( 'numberposts=-1&post_type=post&post_status=any' );

foreach( $allposts as $postinfo) {
	delete_post_meta( $postinfo->ID, 'related_posts' );
	delete_post_meta( $postinfo->ID, 'post_inspiration' );
}
0

#2 Removing custom fields with exceptions

Suppose you want to remove all custom fields post_inspiration except those with value equal to Sherlock Holmes, use this code:

$allposts = get_posts( 'numberposts=-1&post_type=post&post_status=any' );

foreach( $allposts as $postinfo ) {
	$inspiration = get_post_meta( $postinfo->ID, 'post_inspiration' );

	foreach( $inspiration as $value ) {

		if( $value != 'Sherlock Holmes' ){
			delete_post_meta( $postinfo->ID, 'post_inspiration', $value );
		}
	}
}
0

#3 Example of deleting all meta-fields in a certain post

Option 1:

$post_id = 25;
foreach ( get_post_meta( $post_id ) as $key => $val ) {
	delete_post_meta( $post_id, $key );
}

Variant 2 (faster - one request and no extra operations):

$post_id = 25;
global $wpdb;
$wpdb->delete( $wpdb->postmeta, [ 'post_id'=>$post_id ] );
clean_post_cache( $post_id );
0

#4 Other examples

More examples see here.

-3

#5 Delete all meta keys for all posts by meta key name

Let’s assume we have a plugin that added some meta values to posts, but now when we are uninstalling the plugin, we want to delete all the post meta keys that the plugin added. Assuming the plugin added the keys related_posts and post_inspiration.

To delete all the keys use delete_post_meta_by_key(). This would be added to the “uninstall” function:

<?php 
delete_post_meta_by_key( 'related_posts' ); 
delete_post_meta_by_key( 'post_inspiration' );
?>
-9

#6 Demonstration of meta-field removal 

// delete all custom fields with the key `my_key`, post 76
delete_post_meta( 76, 'my_key' );

// delete all custom fields `my_key` with value `Steve`:
delete_post_meta( 76, 'my_key', 'Steve' );

Changelog

Since 1.5.0 Introduced.

delete_post_meta() code WP 6.9.1

wp-includes/post.php 
function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {
	// Make sure meta is deleted from the post, not from a revision.
	$the_post = wp_is_post_revision( $post_id );
	if ( $the_post ) {
		$post_id = $the_post;
	}

	return delete_metadata( 'post', $post_id, $meta_key, $meta_value );
}

Metadatas (any)